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

Available Fields¶

You can retrieve a list of available fields for the /v3/workflowEvents endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/workflowEvents

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 workflowEvents object.

Field	Description	Type	Required for Creation?	Updatable?	Example Value(s)
caseId	The ID of the Case that contains the Workflow Event	Integer	TRUE*	FALSE	1, 2, 3
caseXid	The XID of the Case that contains the Workflow Event	String	TRUE*	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 corresponding to the Workflow Event	Note Object	FALSE	TRUE	{“data”: [{“text”: “Additional information about this Workflow Event”}]}
summary	A summary of the Workflow Event	String	TRUE	TRUE	“New Security Breach Detected by TI Team”

Note

*When creating a Workflow Event, 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 Events¶

The basic format for creating a Workflow Event is:

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

For example, the following query will create a Workflow Event with a summary of “Updated Case name” for the Case with ID 1.

POST /v3/workflowEvents
{
    "caseId": 1,
    "summary": "New Security Breach Detected by TI Team"
}

JSON Response:

{
    "data": {
        "id": 4,
        "eventDate": "2021-03-05T14:54:31Z",
        "dateAdded": "2021-03-05T14:54:31Z",
        "summary": "Updated Case name",
        "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 for the workflowEvents object.

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¶

To retrieve all Workflow Events, use the following query:

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 Single Workflow Event¶

To retrieve a specific Workflow Event, use a query in the following format:

GET /v3/workflowEvents/{workflowEventId}

For example, the following query will return information about the Workflow Event with ID 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"
}

Request Additional Fields¶

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results¶

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Workflow Events¶

The basic format for updating a Workflow Event is:

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

For example, the following query will update the summary for the Workflow Event with ID 4 and add a Note to the Workflow Event.

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,
        "notes": {
            "data": [
                {
                    "id": 7,
                    "text": "Additional information about this Workflow Event",
                    "summary": "Additional information about this Workflow Event",
                    "author": "11112222333344445555",
                    "dateAdded": "2021-03-07T11:17:32Z",
                    "lastModified": "2021-03-07T11:17:32Z",
                    "edited": false,
                    "workflowEventId": 4
                }
            ]
        }
    },
    "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 workflowEvents object.

Attention

You cannot modify system-generated Workflow Events (i.e., Workflow Events with their systemGenerated field set to true). However, you can add Notes that correspond to system-generated Workflow Events.

Delete Workflow Events¶

The basic format to delete a Workflow Event is:

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 query will delete the Workflow Event with ID 4:

DELETE /v3/workflowEvents/4

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

JSON Response:

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