Out-of-sequence conflicts

Out-of-sequence policy transactions are policy transactions with an effective date that is before the effective date of a previous policy transaction on the same policy. Insurers sometimes call these situations out-of-sequence endorsements. PolicyCenter uses the term out-of-sequence.

An out-of-sequence conflict occurs when a policy change has a transaction date later than another policy transaction, but an effective date earlier than that other policy transaction.

The Job API provides endpoints that can be used to identify and resolve out-of-sequence conflicts on policy transactions.

Identifying out-of-sequence conflicts

Policy changes are applied to jobs that are in Draft state, which is when a potential out-of-sequence conflict could be introduced.

While the job is in Draft state, no out-of-sequence warnings are raised, even when a conflicting change is added. When a caller attempts to quote a job that contains one or more out-of-sequence conflicts, a 400 response will be returned with a message informing the caller of the presence of conflicts.

To identify out-of-sequence conflicts on a job, a caller can submit a GET request to the /job/v1/jobs/{jobId}/oos-conflicts endpoint. If are no conflicts, then the request will return an empty response.

For a job that has out-of-sequence conflicts, the response body will contain a conflicts property, which is an array holding one or more conflict objects.

The following example shows an out-of-sequence conflict for date of birth values set for Bill Preston:

{
    "data": {
        "attributes": {
            "conflicts": [
                {
                    "conflictValues": [
                        {
                            "displayValue": "01/01/1975",
                            "effectiveDate": "2019-03-01T00:01:00.000Z"
                        },
                        {
                            "displayValue": "01/01/1977",
                            "effectiveDate": "2019-04-01T00:01:00.000Z"
                        }
                    ],
                    "entity": {
                        "displayName": "Bill Preston",
                        "id": "pc:703",
                        "type": "PolicyContact",
                        "uri": "/job/v1/jobs/pc:204/contacts/pc:703"
                    },
                    "field": "dateOfBirthInternal",
                    "id": "b0aca4bc",
                    "originalValue": "01/01/1970",
                    "yourValue": "01/01/1980"
                }
            ]
        },
        . . .
    }
}

The response body contains the following fields:

conflictValues: An array of objects for each conflict, containing two or more objects
displayValue: A value that is in conflict
effectiveDate: The effective date of the associated value
entity: The target Guidewire entity
field: The field that has the conflict
id: The unique identifier for the conflict
originalValue: The original field value prior to the conflict
yourValue: The latest field value applied by the caller that gave rise to the conflict

Resolving out-of-sequence conflicts

To resolve out-of-sequence conflicts on a job, a caller must submit a POST request to the /job/v1/jobs/{jobId}/oos-conflicts/resolve endpoint. The request body must contain an overrides field, which is an array of override selections for resolving the conflicts. All conflicts must be resolved in the POST.

To retain the original field values for each conflict, thus discarding all subsequent changes, a caller can submit a request body that contains an empty array for the overrides field:

{
  "data": {
    "attributes": {
      "overrides": [ ]
    }
  }
}

If the caller wishes to keep one or more changes to any conflicted fields, then the request body must explicitly declare value selections for all fields that are in conflict. In this case, the

overrides

array must contain an object for each conflict, each having the following properties:

id: The conflict ID, as a string
resolution: A string value of either acceptYours or discardYours

As previously mentioned, each conflict object contains an originalValue and yourValue field. When resolving conflicts, a caller must choose which of those values to retain. To keep the original value, the caller would apply the discardYours value to the resolution property. Otherwise, the caller would apply the acceptYours value to the property.

In the following example request body, the conflicting birthdates for Bill Preston are resolved by choosing the value indicated by the yourValue field in the initial conflict object:

{
  "data": {
    "attributes": {
      "overrides": [ 
        "id": "b0aca4bc",
        "resolution": "acceptYours"
      ]
    }
  }
}

Example: Identifying and resolving out-of-sequence conflicts

It is possible to create multiple out-of-sequence conflicts on a job. This example shows how to resolve three conflicts on the same job.

Consider the following sequence:

In the initial job, an account was created for Bill Preston, his date of birth was set to January 1, 1970, and his address was set to null. Additionally, the number of employees at his company was set at 0.
In the first change to the job, Bill's date of birth was revised to January 1, 1975, and he was given an address, the first line of which is 24 Appletree Rd.
In the second change, Bill's date of birth was revised to January 1, 1977, and the number of employees at his company was raised to 2.
In the third change, Bill's date of birth was revised yet again, to January 1, 1980, and the first line of his address was changed to 88 Maple Lane. Also, the number of employees at his company was changed to null.

The above information, in table form:


Sequence	Date of birth	Address	Employee count
1	1970-01-01	null	0
2	1975-01-01	24 Appletree Rd.
3	1977-01-01		2
4	1980-01-01	88 Maple Lane	null

After these changes have been submitted, a call to /job/v1/jobs/{jobId}/oss-conflicts returns the following response:

{
  "data": {
    "attributes": {
      "conflicts": [
        {
          "conflictValues": [
            {
              "displayValue": "01/01/1975",
              "effectiveDate": "2019-03-01T00:01:00.000Z"
            },
            {
              "displayValue": "01/01/1977",
              "effectiveDate": "2019-04-01T00:01:00.000Z"
            }
          ],
          "entity": {
            "displayName": "Bill Preston",
            "id": "pc:703",
            "type": "PolicyContact",
            "uri": "/job/v1/jobs/pc:204/contacts/pc:703"
          },
          "field": "dateOfBirthInternal",
          "id": "b0aca4b",
          "originalValue": "01/01/1970",
          "yourValue": "01/01/1980"
        },
        {
          "conflictValues": [
            {
              "displayValue": "Address Line 1; Future Change",
              "effectiveDate": "2019-03-01T00:01:00.000Z"
            },
            {
              "displayValue": "Address Line 1; Future Change",
              "effectiveDate": "2019-04-01T00:01:00.000Z"
            }
          ],
          "entity": {
            "displayName": "1: Address Line 1; OOS Change, CA",
            "id": "201",
            "type": "PolicyLocation",
            "uri": "/job/v1/jobs/pc:204/locations/201"
          },
          "field": "addressLine1Internal",
          "id": "df78662",
          "originalValue": "",
          "yourValue": "Address Line 1; OOS Change"
        },
        {
          "conflictValues": [
            {
              "displayValue": "2",
              "effectiveDate": "2019-04-01T00:01:00.000Z"
            }
          ],
          "entity": {
            "displayName": "1: Address Line 1; OOS Change, CA",
            "id": "201",
            "type": "PolicyLocation",
            "uri": "/job/v1/jobs/pc:204/locations/201"
          },
          "field": "employeeCountInternal",
          "id": "47761d4",
          "originalValue": "0",
          "yourValue": ""
        }
      ]
    },
    . . .
}

The same response can be constrained using field selection, by appending ?fields=conflicts.id,conflicts.field,conflicts.originalValue,conflicts.yourValue to the request URL:

{
    "data": {
        "attributes": {
            "conflicts": [
                {
                    "field": "dateOfBirthInternal",
                    "id": "b0aca4b",
                    "originalValue": "01/01/1970",
                    "yourValue": "01/01/1980"
                },
                {
                    "field": "addressLine1Internal",
                    "id": "df78662",
                    "originalValue": "",
                    "yourValue": "88 Maple Lane"
                },
                {
                    "field": "employeeCountInternal",
                    "id": "47761d4",
                    "originalValue": "0",
                    "yourValue": ""
                }
            ]
        }
    }
}

Note that in the response object the JSON null type is represented by an empty string.

To resolve these conflicts, choices must be made between the original values and the most recent values, and this information must be passed in the request body to POST /job/v1/jobs/{jobId}/oss-conflicts/resolve:

{
  "data": {
    "attributes": {
      "overrides": [
        {
          "id": "b0aca4b",
          "resolution": "acceptYours"
        },
        {
          "id": "df78662",
          "resolution": "acceptYours"
        },
        {
          "id": "47761d4",
          "resolution": "discardYours"
        }

      ]
    }
  }
}

Following this post, Bill's birthdate will be January 1, 1980, his address will be 88 Maple Lane, and the number of employees at his company will be set to "0".