The rating framework

PolicyCenter job workflows quantify the financial implications (the cost to the insured) from each job. Of course, submission jobs and policy change jobs have financial implications. In addition, other job types generate financial implications for the insured.

  • Costs for renewals, such as renewal prices
  • Costs for cancellations, such as refunds or cancellation charges

The entire process of offering a policy with a set of terms to an insured at a particular price is called quoting. Quoting includes the following steps.

  1. Collect data about what the insured wants.
  2. Validate the policy data.
  3. Decide whether the policy requires underwriting approval.
  4. Obtain costs or a set of costs for policy coverage for the insured. This step is called rating.
  5. Finally, display the quote to the agent or customer.

This topic primarily discusses rating. Specifically, it discusses how to integrate your own rating code into PolicyCenter.

Many rating costs correspond to a specific object or coverage, for example a personal auto coverage. Costs can also represent taxes and surcharges that apply across an entire policy period. Costs can represent entire policies, in the case of umbrella coverage policies.

When PolicyCenter needs to rate a policy, it calls the registered implementation of the IRatingPlugin rating plugin interface to rate the policy. The rating plugin is the main entry point to the rating process.

To write your own code that rates policies, your main task is to implement the rating plugin, or modify the built-in implementation that PolicyCenter includes. The built-in implementation of the rating plugin is the Gosu class gw.plugin.policyperiod.impl.SysTableRatingPlugin. It uses other related classes such as AbstractRatingEngine and CostData. This documentation refers collectively to the rating plugin implementation its various related classes as the default rating engine. Review the built-in code to more deeply understand the default behavior of this rating engine.

If you use Guidewire Rating Management, you use the PCRatingPlugin rather than the SysTableRatingPlugin. The PCRatingPlugin is described later in this topic.

Any rating plugin implementation must perform two main tasks.

  1. Alter the set of costs (cost entity instances) in the policy entity graph. The rating plugin has only one method. When the method returns, the branch must contain the correct set of cost objects that represent pricing for the entire policy period.

    PolicyCenter later reads the cost information and creates onset and offset transactions. PolicyCenter sends the onset and offset transactions to your billing system.

  2. Notify PolicyCenter that the full set of cost information (the quote) is complete and valid. If there are errors, the plugin marks it as invalid. The default rating engine code marks the quote valid by default. If the default rating code catches any exceptions, it logs the error and marks the quote invalid.

    The default rating engine contains code to force a failed quote for certain test cases. If you use the built-in rating plugin, remove that code before pushing your code to a production system. Look in SysTableRatingPlugin.gs in the ratePeriodImpl method.

You might make only minor changes to the built-in rating plugin implementation. Most of the rating code for typical insurers are in separate rating engine classes for each line of business. Each line-specific rating engine extends the AbstractRatingEngine class. Additionally, consider encapsulating your actual algorithm into separate Gosu classes, one for each type of premium.

To modify rating for a built-in line of business, modify the built-in rating engine class or create a new subclass based on the built-in class.

To rate a new line of business, create a new subclass of AbstractRatingEngine that handles that line of business. If you create any new rating engine subclasses, you must also change the rating plugin method that instantiates and initializes the rating engine subclass based on the line of business. Do not forget to add that code.

The built-in rating engine general algorithm performs the following operations.

  1. Find all change dates in the policy. First, find all dates on which anything changes in the policy in that branch. These are also known as slice dates.
  2. Traverse down the graph on each slice date. For each date on which anything changes, traverse the policy graph downward from its root and calculate costs for this slice date. Each cost represents the cost of everything that can be rated in slice mode for that date. In PolicyCenter revisioning terminology, slice mode is a way of looking at a policy from a specific point in effective time. The abstract rating engine class automatically handles the date detection and revisioning logic associated with this step.
  3. Calculate costs for each slice for every rating line. The abstract rating engine class next calculates the costs for the policy as it exists in effective time between the current slice date and the next slice date. However, costs generated in this step are not yet prorated. The rating engine works this way because it is a common design pattern to integrate with existing rating engines. Suppose an insured requests a policy change to be effective three days before the end of the policy period. The change adds five vehicles to the policy and it is the last change of the policy period in effective time. For this last slice date, the rating engine calculates the policy cost with new vehicles as if they were for the whole period, not just three days. During this step, each rating line sets some cost data properties, including effective and expiration dates based on the time between the current slice date and the next slice date. This is the step in which you might call out to an external rating engine. Be aware that the default rating engine assumes the rating engine responds synchronously.

    This is the critical part of your rating code for costs that make sense in slice mode. Consider encapsulating your actual algorithm into separate Gosu classes, one for each type of premium.

  4. Combine costs for all slices and prorate the costs. PolicyCenter merges any costs if two costs match all of the following conditions.
    • Costs are for the same type of premium, such as the same type of cost for the same car and same coverage
    • Costs are adjacent in effective time
    • Costs have the same rating result, in other words the same non-prorated premium and same rate

    Next, the rating engine prorates slice mode costs based on the cost effective and expiration date properties set in the previous step. PolicyCenter skips costs that already have an actual amount in its ActualAmount property because that means that the rating engine already prorated it. The abstract rating engine class automatically handles date detection and revisioning logic associated with this step.

  5. Calculate costs that depend on previous steps (window mode costs). Next, the line-specific rating engine rates the costs that apply to the entire policy period. For example, many types of discounts and taxes depend on getting sums of the slice-mode costs. If you support flat-rated costs, calculate them in this step.

    This is the critical part of rating code for costs that make sense only as calculations using period-wide subtotals. Consider encapsulating your actual algorithm into separate Gosu classes, one for each type of premium.

  6. Convert rating results into cost entity instances. The rating engine must adjust the rows in the database to match the rating results. Up until this step, all the rating happens on CostData objects. Cost data objects are non-entity class instances that mirror the role of actual Cost entity instances. There are subclasses of CostData for each cost type, effectively mirroring the various line-of-business-specific subtypes of the Cost entity. There are several parts of this conversion process.
    1. Update reusable cost entity instances. If the rating engine can reuse an existing cost entity instance, the rating engine updates the cost to match an updated cost data object. The rating engine updates the cost’s effective/expiration dates, all the rating-related properties, and all amount-related properties. The rating engine sets the properties in the cost entity instance to the values in the cost data object.
    2. Create new cost entity instances if necessary. If the rating engine cannot find an existing cost entity instance for this cost, the rating engine creates a new cost. Generally speaking, this means that there is no cost that matches the cost’s key values and is effective on the effective date of the cost data. The rating engine then adds a new cost by cloning an existing cost entity instance that matches on its same cost key but for different effective dates. This ensures that the new cost entity instance shares the same version list because they have the same fixed ID value.
    3. Delete untouched cost entity instances. Cost entity instances from previous rating requests may no longer be relevant. For example, if you rate a policy and then remove a coverage, costs for that coverage no longer apply. If any cost entity instances do not match any cost data objects in the recent rating request, the default rating engine deletes the cost entity instances. Before rating begins, the rating engine makes a temporary list containing all cost entities for this policy. As the rating engine converts rating results into Cost entity instances, it removes any updated (reused) entities from the list. After the rating engine iterates across all cost data objects, any cost entity instances still in this list match no cost data objects in the current request. The relevant Gosu code refers to this as the untouched list of costs. The rating engine removes all entities in that list.

This general algorithm works for typical lines of business, and generally speaking results in easy-to-maintain and easy-to-understand code. It also helps that for slice mode changes, the abstract rating engine class handles the more complex parts of revisioning (date detection, cost merging, prorating) automatically.

Some lines of business are ill-suited to this approach, however. For example, in the United States for workers’ compensation, regulators mandate a certain rating algorithm that varies greatly from the way most other lines of business generate costs.