Routing related API calls in clustered environments

To improve performance and reliability, you can install multiple ClaimCenter servers in a configuration known as a cluster. A ClaimCenter cluster distributes client connections among multiple ClaimCenter servers, reducing the load on any one server. If one server fails, the other servers seamlessly handle its traffic. For more information on clusters, refer to the Administration Guide.

When ClaimCenter is running in a cluster, it is possible for related system API calls to be routed to different nodes. This can cause problems, such as Concurrent Data Change Exceptions. Typically, multiple related system API calls need to be routed to the same node.

There are two ways that you can ensure a series of related system API calls are routed to the same instance: session IDs (which is the default behavior) and cookies.

Using session IDs

Within the context of system API calls in a clustered environment, a session ID is an arbitrary string generated by the caller application to identify related API calls. The ID is passed in the header of each request. Every request that uses a given session ID will be routed to the same node in the cluster. The header key for a session ID is x-gwre-session.

For example, suppose that a caller application makes the following calls to ClaimCenter cluster:

  1. A POST to create an activity.
  2. A PATCH to update the activity.
  3. A POST to create a note on the activity.

All three calls include the following header:

x-gwre-session: 09d0fbf0-243c-4337-a582-725df8d33e39

Because all three calls specify the same session ID, all three calls will be routed to the same node.

Session IDs is the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you do not need to make any special request to Guidewire Cloud Operations.

Using cookies

Within the context of system API calls in a clustered environment, a cookie is an arbitrary string generated by Guidewire Cloud Platform that can be used to identify subsequent related API calls.

If a request header does not contain an x-gwre-session header key, the Guidewire Cloud Platform generates a cookie and returns it in the response header with a Set-Cookie header key. Subsequent calls can include this cookie in the request header using the Cookie header key. Every request that uses a given cookie will be routed to the same node in the cluster that generated the cookie.

For example, suppose that a caller application makes the following calls to ClaimCenter cluster:

  1. A POST to create an activity
    • The request header contains no x-gwre-session header key.
    • The response header contains the following: Set-Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355; Path=/
  2. A PATCH to update the activity.
    • The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355
  3. A POST to create a note on the activity
    • The request header contains the following: Cookie: gwre=ccd37ca0-f8d3-4a8e-b278-83274d82b355

Because the second and third call specify the cookie returned by the first call, the second and third call are routed to the same node that processed the first call.

Cookies are not the default behavior of the Guidewire Cloud Platform. If you wish to use this option, you must request this from Guidewire Cloud Operations.

Comparing session IDs and cookies

Under most circumstances, it may be easier to use session IDs.

  • Session IDs are generated by the caller application.
  • Session IDs do not require the caller application to identify information in a response header and then manage the storage that information for later use.
  • Session IDs are the default behavior for Guidewire Cloud Platform.

If you wish to use cookies, you must request this from Guidewire Cloud Operations.