Update the properties of a case

It is possible to update some of the properties on an Action Management case via the PUT Case endpoint. This page describes the available properties for update, and the procedure for performing the update.

Case properties that accept updates

The following case properties can be updated via the Action Management public API. Properties in bold cannot be null/empty.

Procedure

To start, get an existing case via the Get Case endpoint.

Request
GET  https://<host>/v1/actionmanagement/hubs/6435/cases/2009631
Accept: application/json
Authorization: Bearer <access_token>
Response
{
    "id" : 2009631,
    "name" : "Example case",
    "workflowId" : 3536,
    "cost" : 250,
    "triggerId" : 7315,
    "triggerName" : "Example trigger",
    "dateCreated" : "2021-10-01T00:00:00-07:00",
    "dateModified" : "2021-10-04T00:00:00-07:00",
    "listValues" : [ {
        "listId" : 23,
        "id" : 987,
        "name" : "In Progress",
        "type" : "status",
        "isOpen" : true
    },
    {
      "listId" : 24,
      "id" : 876,
      "name" : "Critical",
      "type" : "severity",
      "isHigh" : true
    } ],
    "roles" : [ {
        "id" : 3456,
        "caseId" : 2009631,
        "name": "Case Manager",
        "users" : [ {
            "id" : 8790,
            "userName" : "exampleUser8790",
            "isActive" : true,
            "links" : {
                    "self": "https://<host>/v1/hubs/6435/enduserlists/201/users/8790"
                }
            } ]
        } ]
    },
    {
        "id" : 3457,
        "caseId" : 2009631,
        "name": "Watcher",
        "users" : []
    } ],
    "source" : {
        "responseId" : "452651",
        "surveyId" : "p41560",
        "sourceId" : "s3"
    },
    "links" : {
        "self" : "http://<host>/v1/actionmanagement/hubs/96/cases/2009631",
        "notes" : "http://<host>/v1/actionmanagement/hubs/96/cases/2009631/notes"
    }
}

To update a case, change the properties in the GET response you want to update, and submit it back to the API in a Case PUT request.

In this example, we will update the name and cost of the case, and add a due date.

Request
PUT  https://<host>/v1/actionmanagement/hubs/6435/cases/2009631
{
    "id" : 2009631,
    "name" : "Example case with an updated name",
    "workflowId" : 3536,
    "cost" : 500,
    "triggerId" : 7315,
    "triggerName" : "Example trigger",
    "dateCreated" : "2021-10-01T00:00:00-07:00",
    "dateModified" : "2021-10-04T00:00:00-07:00",
    "dateDue" : "2021-10-31T00:00:00-07:00",
    "listValues" : [ {
        "listId" : 23,
        "id" : 987,
        "name" : "In Progress",
        "type" : "status",
        "isOpen" : true
    },
    {
      "listId" : 24,
      "id" : 876,
      "name" : "Critical",
      "type" : "severity",
      "isHigh" : true
    } ],
    "roles" : [ {
        "id" : 3456,
        "caseId" : 2009631,
        "name": "Case Manager",
        "users" : [ {
            "id" : 8790,
            "userName" : "exampleUser8790",
            "isActive" : true,
            "links" : {
                    "self": "https://<host>/v1/hubs/6435/enduserlists/201/users/8790"
                }
            } ]
        } ]
    },
    {
        "id" : 3457,
        "caseId" : 2009631,
        "name": "Watcher",
        "users" : []
    } ],
    "source" : {
        "responseId" : "452651",
        "surveyId" : "p41560",
        "sourceId" : "s3"
    }
}
Accept: application/json
Authorization: Bearer <access_token>

The API will respond with 200 (OK) if the update request was successful. The response will contain the updated case. Note that dateModified will be automatically updated.

Response
{
    "id" : 2009631,
    "name" : "Example case with an updated name",
    "workflowId" : 3536,
    "cost" : 500,
    "triggerId" : 7315,
    "triggerName" : "Example trigger",
    "dateCreated" : "2021-10-01T00:00:00-07:00",
    "dateModified" : "2021-10-22T00:00:00-07:00",
    "dateDue" : "2021-10-31T00:00:00-07:00",
    "listValues" : [ {
        "listId" : 23,
        "id" : 987,
        "name" : "In Progress",
        "type" : "status",
        "isOpen" : true
    },
    {
      "listId" : 24,
      "id" : 876,
      "name" : "Critical",
      "type" : "severity",
      "isHigh" : true
    } ],
    "roles" : [ {
        "id" : 3456,
        "caseId" : 2009631,
        "name": "Case Manager",
        "users" : [ {
            "id" : 8790,
            "userName" : "exampleUser8790",
            "isActive" : true,
            "links" : {
                    "self": "https://<host>/v1/hubs/6435/enduserlists/201/users/8790"
                }
            } ]
        } ]
    },
    {
        "id" : 3457,
        "caseId" : 2009631,
        "name": "Watcher",
        "users" : []
    } ],
    "source" : {
        "responseId" : "452651",
        "surveyId" : "p41560",
        "sourceId" : "s3"
    },
    "links" : {
        "self" : "http://<host>/v1/actionmanagement/hubs/96/cases/2009631",
        "notes" : "http://<host>/v1/actionmanagement/hubs/96/cases/2009631/notes"
    }
}

Error responses

Not all updates to the Action Management case will be accepted. Specific rules need to be followed to maintain data integrity.

404 (Not Found) response

The API will respond with 404 if the GET or PUT requests reference a case ID or hub ID that does not exist, or if the request references a hub the user does not have permission to access.

400 (Bad Request) response

The Case PUT response status will be 400 (Bad Request) if the update request contains invalid data. Examples of invalid requests include:

  • Wrong format (e.g. XML instead of JSON)

  • Missing required properties (e.g. name)

  • Using the wrong data type for a property (e.g. a text string for cost)

  • Attempting to update a property that cannot be updated (e.g. dateCreated)

  • Using a nonexistent or invalid ID for workflowId or triggerId

  • Adding an item to listValues that does not match an existing list item on the hub

  • Adding an item to roles that does not match an existing role on the hub

  • Adding a nonexistent or invalid user to a role