Issues specific to policy changes
Changing producers
In the context of a policy change, you can change a policy's producer of service without changing the producer of record. For more information, see Policy producers.
Preemptions
A preemption is an event that occurs when two or more jobs are created from the same base policy period. The first job to be bound preempts the second job. If you want to continue with the second job, it must be modified to handle the changes made by the first job. Preemptions occurs most commonly with policy changes.
For example, suppose that there is a bound personal auto policy with a single car. A policy change is started to add a motorcycle to the policy. Then, while the first job is still in progress, a second policy change is started that adds a van to the policy. The motorcycle job has no knowledge of the van, and the van job has no knowledge of the motorcycle. If the motorcycle job is bound first, it will preempt the van job. The policy now has both a car and a motorcycle on it. The van job was only aware of the car. Before the van policy change can be completed, it must be modified to include the motorcycle.
PolicyCenter provides support for working with preemptions. PolicyCenter identifies when a job has been preempted. It provides a list of information on the preempting job that is not present in the preempted job. It also provides "handle preemption" functionality that copies information from the preempting job over to the preempted job. For more information, see the Application Guide.
Similarly, Cloud API provides support for preemptions. For a preempted job, you can view information about the preempting job and execute "handle preemption" functionality. Similarly, when a policy change is bound and there is an existing renewal for the policy, you can apply changes from the policy change to the renewal.
Identifying that a job has been preempted
When a job has been preempted, attempts to bind the job fail. PolicyCenter returns a BadInputException similar to the following:
"userMessage": "Cannot take action 'bind-and-issue'. See the details element for further
information.",
"details": [
{
"message": "Branch 7888143943, 12/07/2021, 06/07/2022, 0006260834 has preemptions."
}
]
You can view information about the preempting job. If you want to bind the current job, you must handle the preemptions.
Viewing preemption information
Use the following endpoint to view information about a job's preemptions:
- GET
/job/v1/jobs/{jobId}/preemptions
The /preemptions
endpoint returns two main types of information:
- An array of job diffs
- Information about the preempting job
The diffs
array
The diffs
array identifies all of the changes between the base job
and the preempting job. These are the changes that are not in the preempted job but
would need to be for the preempted job to be bindable.
Each member of the array identifies one difference between the base job and the
preempting job. This includes the object (entity
), the label of the
diff field (field
), the base job value
(existingValue
) and the preempting job value
(changedValue
). The following code shows the syntax of each job
diff array member.
{
"changedValue": <value>,
"entity": {
"displayName": <display name>,
"id": <id>
},
"existingValue": <value>,
"field": <value>
}
The difference can pertain to the value of a single field. For example, the following
payload indicates that on a Medical Payments coverage object, the
choiceTerm1
field in the base job was 5000, but the preempting
job changed it to 15000.
{
"changedValue": "15,000",
"entity": {
"displayName": "Medical Payments",
"id": "85"
},
"existingValue": "5,000",
"field": "choiceTerm1"
}
The difference can also pertain to the addition or removal of an object. When this occurs, a "√" is used to indicate the object is present, and a "" (an empty string) is used to indicate the object is absent. For example, the following payload indicates that a 2000 Honda Civic was not present in the base job but was present in the preempting job. (In other words, the preempting job added a Honda Civic.)
{
"changedValue": "√",
"entity": {
"displayName": "2000 Honda Civic in California",
"id": "32"
},
"existingValue": "",
"field": "2000 Honda Civic in California"
},
The preempting job
The payload also includes information about the preempting job, including:
- The job itself
- The job's effective date
- The job number
- The job type
Preemption payload example
For example, suppose that there is a personal auto policy with an Acura Integra. At roughly the same time, two policy changes are started:
- First policy change:
- Job number: 0004375724
- Job id: pc:421
- Effective date: 11/05/2021
- Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
- Second policy change:
- Job number: 0004408964
- Job id: pc:505
- Effective date: 11/06/2021
- Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley
The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a preemption.
The following shows a portion of the response payload for a GET
/preemptions
for job pc:505. Note that the array of diffs in the
payload contains the following information.
- The effective date for the preempting job
- The vehicle for the preempting job
- The vehicle's collision coverage for the preempting job
- The vehicle's comprehensive coverage for the preempting job
- The vehicle driver for the preempting job
The payload also contains information about the preempting job.
GET /job/v1/jobs/pc:505/preemptions
{
"count": 1,
"data": [
{
"attributes": {
"diffs": [
{
"changedValue": "11/05/2021",
"entity": {
"displayName": "4509454228, 11/04/2021, 05/04/2022, 0004375724",
"id": "pc:421",
"type": "Job",
"uri": "/job/v1/jobs/pc:421"
},
"existingValue": "11/04/2021",
"field": "writtenDate"
},
{
"changedValue": "√",
"entity": {
"displayName": "2000 Honda Civic in California",
"id": "32"
},
"existingValue": "",
"field": "2000 Honda Civic in California"
},
{
"changedValue": "√",
"entity": {
"displayName": "Collision",
"id": "64"
},
"existingValue": "",
"field": "Collision"
},
{
"changedValue": "√",
"entity": {
"displayName": "Comprehensive",
"id": "63"
},
"existingValue": "",
"field": "Comprehensive"
},
{
"changedValue": "√",
"entity": {
"displayName": "Alicia Shirley",
"id": "15"
},
"existingValue": "",
"field": "Assigned Driver: Alicia Shirley"
}
],
"job": {
"displayName": "0004375724",
"id": "pc:421",
"type": "Job",
"uri": "/job/v1/jobs/pc:421"
},
"jobEffectiveDate": "2021-11-05T00:01:00.000Z",
"jobNumber": "0004375724",
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
},
...
Handling preemptions
Once a job has been preempted, it can no longer be bound in its current state. This is because the base policy period has been modified by the preempting job, and the preempted job is now missing information present in the base policy period.
PolicyCenter provides the ability to handle preemptions. This is an action you can take on a preempted job to copy over the changes made by the preempting job. Handling a preemption brings a preempted job in line with the new version of the base period. Once you have handled preemptions for a job, you can bind it.
To handle preemptions through Cloud API, use the following endpoint:
- POST
/job/v1/jobs/{jobId}/handle-preemptions
You do not need to provide a request body.
Typically, handling a preemption modifies the contents of a job. Therefore, you need to quote the job prior to binding it, even if you quoted the job prior to the preemption.
Example of handling preemptions
In the previous topic, there was an example of a personal auto policy with an Acura Integra. At roughly the same time, two policy changes are started:
- First policy change:
- Job number: 0004375724
- Job id: pc:421
- Effective date: 11/05/2021
- Material changes: Adds a Honda Civic and associated coverages for driver Alicia Shirley
- Second policy change:
- Job number: 0004408964
- Job id: pc:505
- Effective date: 11/06/2021
- Material changes: Adds a Toyota Prius and associated coverages for driver Alicia Shirley
The first policy change is bound, causing that job to preempt the second job. As a result, the second job now has a preemption.
Now, suppose you want to handle preemptions for the second job and then bind it. (For clarity sake, portions of the response payload have been omitted in the following examples.)
POST /job/v1/jobs/pc:505/handle-preemptions
<no request body>
RESPONSE:
{
"data": {
"attributes": {
"job": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Draft",
"name": "Draft"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
}
}
}
}
POST /job/v1/jobs/pc:505/quote
<no request body>
RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Quoted",
"name": "Quoted"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
},
"taxesAndSurcharges": {
"amount": "94.00",
"currency": "usd"
},
"totalCost": {
"amount": "1396.00",
"currency": "usd"
},
"totalPremium": {
"amount": "1302.00",
"currency": "usd"
}
}
}
}
POST /job/v1/jobs/pc:505/bind-and-issue
<no request body>
RESPONSE:
{
"data": {
"attributes": {
"id": "pc:505",
"isPreempted": false,
"jobNumber": "0004408964",
"jobStatus": {
"code": "Bound",
"name": "Bound"
},
"jobType": {
"code": "PolicyChange",
"name": "Policy Change"
}
}
}
}
Applying changes to a renewal
It is possible for a policy change to preempt a future renewal whose state is either draft or bound. When the policy change is bound, the user interface provides the option of applying the changes in the preempting job to the renewal. This is similar to "handle preemption" functionality, but there are differences:
- The copying of information is initiated from the preempting job, not the preempted job.
- The copying of information is optional. If you choose to not copy the information, you can still bind the renewal.
To apply changes from a policy change to a renewal through Cloud API, use the following endpoint:
- POST
/job/v1/jobs/{jobId}/apply-changes-to-renewal
You do not need to provide a request body.
Once the changes are applied to the renewal, you need to quote (or requote) the renewal before it can be bound.
Identifying when a renewal exists
When you execute a policy change from the PolicyCenter user interface, there is a button that identifies a renewal exists. This button gives you the option to copy changes to the renewal.
When you execute a policy change from Cloud API, you can identify whether there is an
existing renewal by checking the links
array of the response
payload. If there is an apply-changes-to-renewal
member, the job's
policy has a renewal and you may want to consider applying the policy changes to
that renewal.
apply-changes-to-renewal
member, indicating the changed policy
has a renewal."links": {
..
"activity-patterns": {
"href": "/job/v1/jobs/pc:232/activity-patterns",
"methods": [
"get"
]
},
"apply-changes-to-renewal": {
"href": "/job/v1/jobs/pc:232/apply-changes-to-renewal",
"methods": [
"post"
]
},
"contacts": {
"href": "/job/v1/jobs/pc:232/contacts",
"methods": [
"get"
]
},
...