Checksums

A checksum is a string value that identifies the "version" of a particular resource. Cloud API calculates checksums as needed based on information about the underlying entities in the PolicyCenter database.

When a process modifies data, either through user action, Cloud API, or some other process, Cloud API calculates 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"
    }
}

Generating checksums

Checksums are always string values generated by Guidewire based on all the values in the database for the associated entity. Checksums are typically complex string values, such as c689ec1403a489ed7bc3ca6e8ce4f73e.

An resource's checksum is modified when any field in the associated entity changes, whether that field is exposed to Cloud API or not. For example, the Activity entity has a field named EmailTemplate which stores the id of any email template associated with the activity. This field is not exposed in Cloud API. However, if this field is changed for a given activity, either through the user interface or by some other process, this will increment the Activity resource's checksum.

In some cases, checksums are set to simple integer values, such as 1, and a change to the entity simply increments the integer value by 1. However, when a checksum is an integer, there is 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 Cloud API requests to only the checksums returned in previous responses.

Resources that map to multiple data model entities

Most resources correspond to a single data model entity. For example, the properties in the Activity resource map to a single data model entity - the Activity data model entity.

However, there are resources that combine fields from multiple data model entities. For example, the User resource has fields that map to the User data model entity (such as externalUser), the Credential data model entity (such as username), and the UserContact data mode entity (such as cellphone).

In the base configuration, when a resource maps to multiple data model entities, a change to any one of the underlying entities increments the resource's checksum. Custom resources that map to multiple data model entities can also be configured to have the checksum reflect changes to any of the underlying data model entities. For more information, see the Cloud API Developer Guide.