Workflow Events

Workflow Events, also known as Timeline Events, represent changes made to a Workflow Case. When an action is performed in a Case, a Workflow Event is automatically added to the Case’s timeline. You can also manually add a Workflow Event to a Case.

Endpoint: /api/v3/workflowEvents

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

OPTIONS /v3/workflowEvents

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

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
caseId	The ID of the Case that contains the Workflow Event	Integer	TRUE [1]	FALSE	1, 2, 3
caseXid	The XID of the Case that contains the Workflow Event	String	TRUE [1]	FALSE	“a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”
eventDate	The date and time when the Workflow Event took place	Date	FALSE	TRUE	“2021-04-30T12:30:00Z”
notes	A list of Notes added to the Workflow Event	Note Object	FALSE	TRUE	{“data”: [{“text”: “Additional information about this Workflow Event”}]}
summary	The Workflow Event’s summary	String	TRUE	TRUE	“Notes about Case uploaded to SOC team shared drive”

[1] (1,2)

When adding an Workflow Event 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/workflowEvents endpoint:

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

OPTIONS /v3/workflowEvents/tql

Create Workflow Events

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

POST /v3/workflowEvents
{
    "caseId": 1,
    "summary": "Summary of the Workflow Event"
}

For example, the following request will add a Workflow Event with a summary of “Notes about Case uploaded to SOC team shared drive” to the Case whose ID is 1:

POST /v3/workflowEvents
{
    "caseId": 1,
    "summary": "Notes about Case uploaded to SOC team shared drive"
}

JSON Response:

{
    "data": {
        "id": 4,
        "eventDate": "2021-03-05T14:54:31Z",
        "dateAdded": "2021-03-05T14:54:31Z",
        "summary": "Notes about Case uploaded to SOC team shared drive",
        "systemGenerated": false,
        "link": "https://app.threatconnect.com/api/v3/cases/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/workflowEvents endpoint.

Note

Creating a Workflow Event only adds the Workflow Event to the Case’s timeline. It does not perform the action indicated in the Workflow Event’s summary.

Retrieve Workflow Events

Retrieve All Workflow Events

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

GET /v3/workflowEvents

JSON Response:

{
    "data": [
        {
            "id": 1,
            "eventDate": "2021-03-05T14:48:44Z",
            "dateAdded": "2021-03-05T14:48:44Z",
            "summary": "Case created",
            "systemGenerated": true,
            "link": "https://app.threatconnect.com/api/v3/cases/1"
        },
        {
            "id": 2,
            "eventDate": "2021-03-05T14:49:24Z",
            "dateAdded": "2021-03-05T14:49:24Z",
            "summary": "Added a note",
            "systemGenerated": true,
            "link": "https://app.threatconnect.com/api/v3/notes/1"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Specific Workflow Event

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

GET /v3/workflowEvents/{workflowEventId}

For example, the following request will retrieve data for the Workflow Event whose ID is 1:

GET /v3/workflowEvent/1

JSON Response:

{
    "data": {
        "id": 1,
        "eventDate": "2021-03-05T14:48:44Z",
        "dateAdded": "2021-03-05T14:48:44Z",
        "summary": "Case created",
        "systemGenerated": true,
        "link": "https://app.threatconnect.com/api/v3/cases/1"
    },
    "status": "Success"
}

Update Workflow Events

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

PUT /v3/workflowEvents/{workflowEventId}
{
    {updatedField}: {updatedValue}
}

For example, the following request will update the summary for the Workflow Event whose ID is 4 and add a Note to the Workflow Event:

Hint

To include the notes field in the API response, append ?fields=notes to the end of the request URL.

PUT /v3/workflowEvents/4
{
    "summary": "New Workflow Event summary",
    "notes": {"data": [{"text": "Additional information about this Workflow Event"}]}
}

JSON Response:

{
    "data": {
        "id": 4,
        "eventDate": "2021-03-05T14:48:44Z",
        "dateAdded": "2021-03-05T14:48:44Z",
        "summary": "New Workflow Event summary",
        "systemGenerated": false,
        "link": "https://app.threatconnect.com/api/v3/cases/1"
    },
    "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/workflowEvents endpoint.

Attention

You cannot modify system-generated Workflow Events (i.e., Workflow Events with the systemGenerated field set to true), but you can add Notes to them.

Delete Workflow Events

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

DELETE /v3/workflowEvents/{workflowEventId}

{
    "deletedReason": "Reason for deleting the Workflow Event."
}

Attention

Only Workflow Events that have been manually added to a Case may be deleted.

For example, the following request will delete the Workflow Event whose ID is 4:

DELETE /v3/workflowEvents/4

{
    "deletedReason": "No longer needed this Workflow Event."
}

JSON Response:

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

Delete Workflow Events in Bulk

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