Overview of policy differences

You can view comparisons between policy periods in several places in the PolicyCenter user interface. You can customize the appearance of these differences and customize the underlying logic that determines the differences.

The policy review screen that you can view as part of a policy change job is most common user interface for viewing policy differences.

The top-level trigger for most of the policy-difference code is PolicyCenter application logic calling the registered plugin for the IPolicyPeriodDiffPlugin interface. The plugin has the methods filterDiffItems and compareBranches.

Each difference that the plugin method generates is encapsulated in a difference item (gw.api.diff.DiffItem) object. The difference item represents a single difference between the policy periods. A difference has one of the following types:

An addition of a bean (entity instance) to the policy period graph
A removal of a bean from the policy period graph
A change in a property
A change in the policy period range

Each type of difference is implemented by a separate subclass of DiffItem.

The plugin methods implement different strategies to generate and filter the list of differences between two policy periods. The application flow determines which of these methods is called by user interface.

Difference item generation strategy	Description	What generates differences?	What filters differences?
Database generation of difference items	PolicyCenter compares a policy period to the revision that it was based on. PolicyCenter can calculate changed properties and entities directly from the database. This process is very efficient and accurate. PolicyCenter uses this approach for policy changes and some other application flows. Your code filters out irrelevant differences.	Typically, PolicyCenter generates the differences by using a database query. A rare exception is for Workers’ Compensation and General Liability. In this case, the database query does not generate exposure splits, so the filterDiffItems method in the plugin generates additional differences. See the `WCDiffHelper` and GLDiffHelper classes. These classes handle exposures that split.	The entry point for filtering is the `IPolicyPeriodDiffPlugin` plugin method filterDiffItems. Only customize that method to filter out differences if you are sure no PolicyCenter code ever needs those differences. For example, the application uses the list of differences in the following places. Logic that merges or applies changes from one revision to another. User interface code to display differences. You can filter dynamically based on the difference reason, by using the `DiffReason` typecode parameter on the plugin method. To configure the differences that the tree view displays and how the differences appear, customize a difference tree configuration XML file.
Comparison of two branch graphs	For multi-version jobs and in some other contexts, the policy period difference plugin triggers Gosu code that compares two arbitrary branch graphs and generates a list of differences.	The compareBranches method of the policy period difference plugin uses Gosu code to generate the differences.	This strategy is mostly about generating difference items rather than filtering them. This approach does use a secondary filtering process. To configure the differences that the tree view displays and how the differences appear, customize a difference tree configuration XML file.

Difference item generation strategy

Description

What generates differences?

What filters differences?

Database generation of difference items

PolicyCenter compares a policy period to the revision that it was based on. PolicyCenter can calculate changed properties and entities directly from the database. This process is very efficient and accurate. PolicyCenter uses this approach for policy changes and some other application flows.

Your code filters out irrelevant differences.

Typically, PolicyCenter generates the differences by using a database query.

A rare exception is for Workers’ Compensation and General Liability. In this case, the database query does not generate exposure splits, so the filterDiffItems method in the plugin generates additional differences. See the WCDiffHelper and GLDiffHelper classes. These classes handle exposures that split.

The entry point for filtering is the IPolicyPeriodDiffPlugin plugin method filterDiffItems.

Only customize that method to filter out differences if you are sure no PolicyCenter code ever needs those differences. For example, the application uses the list of differences in the following places.

Logic that merges or applies changes from one revision to another.
User interface code to display differences.

You can filter dynamically based on the difference reason, by using the DiffReason typecode parameter on the plugin method.

To configure the differences that the tree view displays and how the differences appear, customize a difference tree configuration XML file.

Comparison of two branch graphs

For multi-version jobs and in some other contexts, the policy period difference plugin triggers Gosu code that compares two arbitrary branch graphs and generates a list of differences.

The compareBranches method of the policy period difference plugin uses Gosu code to generate the differences.

This strategy is mostly about generating difference items rather than filtering them. This approach does use a secondary filtering process.

To configure the differences that the tree view displays and how the differences appear, customize a difference tree configuration XML file.

PolicyCenter chooses which strategy and, therefore, which plugin method to call based on the context of the request. The following table lists the places where PolicyCenter checks for differences between policy periods, how the check is implemented, and which strategy is used to generate the difference items.

Reason to check for differences	Strategy for generating differences	Description
Policy change transaction	Database generation	The Policy Review page displays what changed between the active branch and the branch upon which it was based.
Renewal transaction	Database generation	The Policy Review page displays what changed between the active branch and the branch upon which it was based.
Rewrite transaction	Database generation	The Policy Review page displays what changed between the active branch and the branch upon which it was based.
Out-of-sequence jobs (of multiple types)	Database generation	PolicyCenter must check whether a job is out of sequence and generate a list of conflicts, if any. If there are conflicts, users must review the list of changes to merge forward to future-effective-dated branches.
Preempted jobs	Database generation	PolicyCenter uses differences in two places in the preemption flow. First, PolicyCenter checks whether a job was preempted. If so, PolicyCenter displays and applies differences between the current branch and its based-on branch. Users must review the list of changes to apply from the preempting branch to the current branch before binding the active job. After PolicyCenter handles the preemption, some changes might conflict with changes already made in the preempted branch. PolicyCenter uses the differences engine and user interface to display those differences.
Integration	Database generation	Integration code might need to notify a downstream system of recent changes. A typical case is comparing a recently bound branch to the branch it was based on. You can generate changes, filter them for your downstream system, and then convert the results to a messaging payload.
Multi-version job policy comparisons	Compare two branch graphs	For a multi-version job, users can compare different versions of a policy and quotes for each one. The two or more non-bound branches share the same `branchID` but the branches are not based directly on each other. Some data is simplified or omitted for display. For example, for the Personal Auto line, the interface compares vehicles, coverage amounts, and resulting costs in the quote. If you add a vehicle, PolicyCenter adds coverages for the new vehicle but does not display the coverages explicitly in the comparison.
Arbitrary historical revision comparisons	Compare two branch graphs	To compare the state of the policy at different times in the policy history, users can select two versions in the same logical period. Even if two branches are in the same logical period, two arbitrary revisions a user wants to compare may not be directly based on each other. PolicyCenter cannot use the efficient database-based comparison mechanism in this case.

The full set of differences that PolicyCenter needs in order to perform the underlying data actions might be more than you want users to view in the user interface.

For example, some application tasks require generating multiple difference items, which you might consolidate and show as a single difference to the user. For another task, you might want to omit some differences between low level properties or window mode changes. You configure what difference items to display in the tree view within the user interface by using a difference tree configuration XML file. You must define one difference tree XML file for each product.