Workflow Events

Workflow 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. Users can also manually add a Workflow Event to a Case.

Endpoint: /api/v3/workflowEvents

Create Workflow Events

The most basic format for creating a Workflow Event is:

POST /v3/workflowEvents/
{
  "caseId": 1,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "summary": "Summary of the Workflow Event"
}

Some Workflow Event types require additional fields when being created. Refer to the following table for a list of available fields for the workflowEvents object:

Field Description Required Type Example Value(s)
caseId The ID of the Case that contains the Event TRUE Integer 1, 2, 3
caseXid The XID of the Case that contains the Event TRUE String “a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”
eventDate The time that the Event is logged FALSE Date “2021-04-30T00:00:00Z”
notes A list of Notes corresponding to the Event FALSE String “{“data”: [{“text”: “Note for New Workflow Event”}]}}”
summary The summary of the Event TRUE String “Workflow Event Summary”

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,
  "caseXid": "a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1",
  "summary": "Updated Case name"
}

JSON Response:

{
  "data": {
    "id": 4,
    "eventDate": "2021-03-05T14:54:31Z",
    "dateAdded": "2021-03-05T14:54:31Z",
    "summary": "Updated Case name",
    "systemGenerated": False
  },
  "message": "Created",
  "status": "Success"
}

Note

Creating a Workflow Event only adds an Event to the Case’s Timeline. It does not perform the action indicated in the 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"
  }],
  "count": 2,
  "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 provided with each returned Workflow Event, refer to the Request Additional Fields for Returned Objects section in this documentation.

Filter Results

To filter returned Workflow Events using ThreatConnect Query Language (TQL), refer to the Filter Results with TQL section in this documentation.

Update Workflow Events

To update a Workflow Event, the basic format is:

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

Refer to the following table for a list of available fields that can be updated for the workflowEvents object:

Field Description Type Example Value(s)
eventDate The time that the Event is logged Date “2021-04-30T00:00:00Z”
notes A list of Notes corresponding to the Event String “{“data”: [{“text”: “Note for New Workflow Event”}]}}”
summary The summary of the Event String “Workflow Event Summary”

For example, the following query will update the summary for the Workflow Event with ID 1.

PUT /v3/workflowEvents/1
{
  "summary": "New Workflow Event summary"
}

JSON Response:

{
  "data": {
    "id": 1,
    "eventDate": "2021-03-05T14:48:44Z",
    "dateAdded": "2021-03-05T14:48:44Z",
    "summary": "New Workflow Event summary",
    "systemGenerated": True,
    "notes": {
      "count": 0
    }
  },
  "message": "Updated",
  "status": "Success"
}

Delete Workflow Events

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

DELETE /v3/workflowEvents/{workflowEventID}

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

For example, the following query will delete the Workflow Event with ID 1:

DELETE /v3/workflowEvents/1

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

JSON Response:

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