Checksums

A checksum is a string value that identifies the "version" of a particular resource. The system APIs calculate checksums as needed based on information about the underlying entities in the PolicyCenter database.

When a process modifies data, either through user action, system APIs, or other process, the system APIs calculate a different checksum for the resource. You can prevent lost updates by checking a resource's checksum before you modify the resource to see if it matches a previously retrieved checksum.

By default, checksums are provided in the response payloads of all GETs, POSTs, and PATCHes.

Checksums can be included in:

  • Request payloads, which is appropriate for:
    • PATCHes
    • Business action POSTs that allow request payloads (such as POST /{activityID}/assign)
  • Request object headers for:
    • DELETEs
    • Business action POSTs that do not allow request payloads

When you submit a request with a checksum, PolicyCenter calculates the checksum and compares that value to the submitted checksum value.

  • If the values match, PolicyCenter determines the resource has not been changed since the caller application last acquired the data. The request is executed.
  • If the values do not match, PolicyCenter determines the resource has been changed since the caller application last acquired the data. The request is not executed, and PolicyCenter returns an error similar to the following: 
    {
    "message": "The supplied checksum '1' does not match the current checksum '2' for the resource with uri '/common/v1/notes/xc:101'",
    "properties": {
        "uri": "/common/v1/notes/xc:101",
        "currentChecksum": "2",
        "suppliedChecksum": "1"
    }
}

In many cases, checksums are simple integer values that are incremented with each update. However, this is not always the case. For some resources, the checksum is a more complicated string value, such as "fwer:3245-11xwj". Also, when a checksum is an integer, there is also no guarantee that the next checksum will be the integer value incremented by one. Guidewire recommends against caller applications attempting to predict what the next checksum value will be. Limit checksums in system API requests to only the checksums returned in previous responses.