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

Available Fields

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

OPTIONS /v3/workflowEvents

Note

To view all fields, including read-only fields, include the ?show=readonly query parameter.

Create Workflow Events

The 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"
  }],
  "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 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}
}

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

The basic format to delete a Workflow Event is:

DELETE /v3/workflowEvents/{workflowEventId}

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

Note

You must specify a deletedReason to delete a 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"
}