Deferring validation

During submission processing, PolicyCenter executes validation to ensure a submission meets all requirements. For example, suppose an insurer has a rule stating that all Personal Auto vehicles must have collision coverage. As the submission is being created, PolicyCenter identifies any vehicles without collision coverage and prevents further processing until the coverage is added.

For Cloud API, this default validation behavior is referred to as immediate validation. In this approach, validation is provided with each call. A validation error in one call can prevent later calls from executing. This approach is appropriate for caller applications that build submissions interactively, such as those backing a user interface.

There is a second behavior called deferred validation. In this approach, validation takes place only after the caller application has put the submission into what it believes to be a consistent state. This is an option for non-interactive caller applications with sufficient authorization. This approach can simplify submission processing by preventing validation checks when the submission is known to be in an inconsistent state.

The deferValidation query parameter

Deferred validation is implemented by use of the deferValidation query parameter. This is a Boolean query parameter that defaults to false. It is available on the following sets of endpoints:

  • Coverable endpoints (such as POST /jobs/{jobId}/lines/PersonalAutoLine/vehicles)
  • Coverage endpoints (such as POST /jobs/{jobId}/lines/{lineId}/coverages)
  • Question endpoints (such as POST /job/v1/jobs/{jobId}/questions)
  • Graph submission endpoint (POST /graph/v1/submissions)

When the query parameter is set to true, the following behaviors are implemented:

  • POST/PATCH of a coverable
    • Disable availability and editability checking for risk model fields. If a risk model field is unavailable, its availability bit will be set and it will be updated anyway.
    • Disable availability checking for typekeys
    • Disable min/max checking for risk model fields
  • POST/PATCH of a coverage
    • Disable availability checking of the coverage (or condition or exclusion) itself
    • Disable availability and editability checking of coverage terms. If a coverage term is unavailable, it will be created and set anyway during the update.
    • Disable availability checking on coverage term options and packages
    • Disable availability checking on coverage term typekeys
    • Disable min/max checking on direct and datetime covterms
  • DELETE of a coverage
    • Allow deletion even if the coverage is marked as required
  • PATCH of question answers
    • Force creation of the associated AnswerDelegate entity if it has not already been created, which means it was unavailable the last time questions were synced
  • POST of graph submissions
    • All the POST behaviors listed above

For example, suppose Personal Auto submission pc:6066 has vehicle 103, which is located in Oklahoma. The caller application plans to do the following:

  1. PATCH the vehicle so that it is located in Texas
  2. POST a "PIP - Texas" coverage to the vehicle

The POST will fail. This is because, when the vehicle was created, the availability logic was cached. This logic identifies that the vehicle is in Oklahoma.

There are two solutions to the problem. You could execute a POST /vehicles/{vehicleId}/sync-coverages before POSTing the coverage. Alternately, you could use the deferValidation query parameter when POSTing the coverage For example:

POST /job/v1/jobs/pc:6066/lines/PersonalAutoLine/vehicles/103/coverages?deferValidation=true

You cannot defer validation when quoting a job. Validation is always executed when the job is quoted.

Authorization to defer validation

The deferValidation query parameter is not available to all callers by default. In order to use the query parameter, the caller must be associated with a role whose role.yaml file has the deferProductModelValidation special permission.

For more information on authorization and special permissions, see the Cloud API Developer Guide.

Limitations to deferred validation

The deferValidation query parameter can reduce the number of times you need to call the /sync endpoints. For example, the query parameter lets you set values that are unavailable given the current state of the job, but that will be available by the time the job data is complete. (Without the query parameter, you would need to call the appropriate /sync endpoint before adding the unavailable values.)

However, the query parameter may not entirely eliminate the need to call the /sync endpoints. For example, suppose you are modifying a job using deferred validation. Initially, there is a coverage that is unavailable. Later, the state of the job data causes the coverage to become available, and the coverage is required when it is available. Because validation has been deferred, there is no indication that a required coverage is missing until you attempt to quote the job. Once the quote fails validation, you will still need to call the appropriate /sync endpoint.