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:
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.