# Concepts Overview
This document provides an overview of the concepts in BriteLines.
# Risk Types
A Risk Type is a collection of a data fields, coverages, and rating logic which models a real world entity like a Vehicle, Home, or Person.
Risk Types have four important concepts associated with them: Fields, Rate Tables, Calculations, and Items.
# Data Fields
Fields are used to define the data that may be collected to rate a risk. The values provided are used for data collection, in underwriting rules, and to determine the premium, limit, and deductible values.
Field values are collected on a Quote in the following ways:
- By user input from an agent, admin, or insured.
- By business rules.
- By third-party partner integrations like VINMASTER or LexisNexis Auto Data Prefill.
Field values are required to be collected under these two circumstances:
- They are referenced by one or more of the Items on the quote. The only way to determine the premium for the Item is to provide the Field with an Answer.
- "Always show this field" is set to
Yesunder Field Settings section
# Field Types
Field Types are used to determine the kind of data that is being collected. The following Field Types are available:
- Option Selection
Field have a default widget they are rendered as. Strings and Numbers use a textbox widget, Booleans use a Yes/No toggle, Option Selections use a dropdown box, and Computeds use a disabled textbox.
A string of text-based characters.
Examples of string field answers:
- Bill Withers (driver's name)
- 417-555-1234 (phone number)
- 123 Fake Street (address street)
- Yes, I don't fully occupy this residence, however... (underwriting questions explanation)
A date with no time information.
Example of a date field answer:
- 2017-10-31 (date of purchase)
A number that arithmetic can be performed on. If you don't plan on performing arithmetic on the Field then use string instead. For example,
Examples of number field answers:
- 24 (dog's weight)
- 1000 (coverage limit)
A field that can only be true or false.
Examples of boolean field answers:
- true (driver took driver training)
- false (car has anti-lock brakes)
A field whose value is determined by a calculation rather than entered by a user. The field value will be evaluated before rating the risk.
Examples of computed fields that are calculated based on another field:
- 30 (driver age with calculation
- 3 (driver points with calculation
# Option Selection
A field whose value can only be one choice out of a list of options. The options for an Option Selection can come from two sources: a pre-defined list or risks of a certain Risk Type.
An option from the pre-defined list contains the following fields:
- Label - Text representation of the given option which will be displayed to user. E.g.
- Value - Internal value of the option which will be used in rating. E.g.
- Reference Name - A reference name which can only be changed from the risk field version it is created in. It will be used to reference the option from different versions. E.g.
Examples of Option Selection field answers:
- Alarm (Anti Theft System from the options None, Alarm, and Passive Disabling Devices)
- Standard (Tier from the options Standard and Elite)
- $1,000 (Medical Expense Limit from the options $1,000, $2,000, and $5,000)
# Using Risk Type as an Option Selection source
Option Selection fields can use risks from other Risk Types as the source of their data. To set this up, add an Option Selection field and click "Use a Risk Type for Options."
Next, choose the Risk Type you would like to use as a source. Finally, choose the Risk Type's sub-field that should be used to display to the user.
For example, imagine you have a Drivers Risk Type as a child of the Policy Risk Type and you would like to give a Vehicle Risk Type a Principal Driver. To set this up, do the following:
- Add an Option Selection field to the Vehicle Risk Type and call it "Principal Driver".
- Click "Use a Risk Type for Options."
- Under Risk Type Name choose the Drivers Risk Type.
- Finally, under Option Display Label Template, add the Risk Type fields that should be displayed for each option.
# Optional Fields
Data Fields which are shown even when not required for rating can be made optional by setting
Field Settings section. This is only for fields which are not used in rating. To mark rating fields as optional use the bc.optional function.
# Default Values
Many Field Types support default values for Data Fields. The default value is assigned to the Field when users first create a risk.
# Data Field Formats
Data Field Formats provide metadata about a Field. This metadata can be used by external systems to better handle or display Fields.
Data Field Formats are also templates for creating common Data Fields. Instead of manually entering all the parameters for the field, Data Field Formats can be used to pre-fill labels, reference names, or Field Types. They can also be used for reference purpose to know the validation criteria or options for fields which use a certain format.
# Rate Tables
Rate Tables are where you can store the data used to map inputs (data fields, other rate tables, or calculations) to outputs (a rate, factor, or anything else). By separating the data and calculations users can make rating changes in a new version and only touch the Rate Tables. The Calculations that use the Rate Table data can remain untouched.
# A Simple Example
To define a Rate Table you will first need to select the Rate Table's data sources. Each data source will add a new column to the Rate Table. The final column holders the values that each row of the Rate Table should resolve to.
For example, we have the following Rate Table called
medicalExpenseLimit field of type Option Selection with the three options from the first column of the table as possible choices.
If the user chooses "1000" during a quote then this table will resolve to 0.0. If they choose "2000" then the table will resolve to 2.0. And so on.
Rate Tables also supports using multiple fields to resolve to one value. Imagine the Rate Table looked like this instead:
If the user chooses a "Standard" tier and territory "2" then the table will resolve to 1.0. If the user chooses a "Preferred" tier and territory "3" then the table will resolve to 0.9.
# Rate Table Sources
Rate Table sources are the inputs that are used to make the Rate Table resolve to a single value. The following types or rating information can be used as a rate table source:
- Data Fields
- Shared Calculations
- Other Rate Tables
Rate Table sources can come from the current Risk Type being edited or its parent Risk Type.
# Sources - Data Fields
Data Fields are the simplest Rate Table sources. The rating engine will map whatever value the user entered into the Data Field to the values in the Rate Table.
# Sources - Shared Calculations
Shared Calculations can also be used as sources. The value that gets mapped to the Rate Table will be the result of the Calculation.
# Sources - Other Rate Tables
Rate Tables can be used as sources to other Rate Tables. The second Rate Table will receive all possible resolution values of the first Rate Table (including default value, if set).
Imagine this Rate Table called
zipToTerritoryTable. It maps a
zip Data Field to a territory:
zipToTerritoryTable could be used as an input to another Rate Table. The second Rate Table will receive whichever territory that
zipToTerritoryTable resolved to.
# Rate Table default value
Rate Table's default value is used when a Rate Table cannot be resolved due to missing references.
Generally speaking, it can be either whatever value you'd use as a Rate Table's output or
When default is
None it means that a Rate Table containing missing references will resolve to
None. That is especially useful when such Rate Table is used as a source for another Rate Table.
In this case second Rate Table will receive
None among the other source Rate Table's possible
resolution values and that
None can be used for mapping just like the rest of the values.
# Adding a default value
There are 2 ways to give Rate Table's a default value:
- Selecting one from the list of pre-defined options. That list is populated with
Noneand all possible output values.
- Specifying a custom value. In order to do so, enter desired value and select it.
# Automatically populating Rate Table data
The following Rate Table sources will automatically populate the table with its possible choices:
- Option Selection Data Field - The table will be populated with the Field's options
- Boolean Data Field - The table will be populated with
- Other Rate Tables - The table will be populated with all possible resolution values from the source Rate Table.
All other Rate Table sources will need explicit resolution instructions via Tiers and Resolution Types.
# Tiers and Resolution Types
Tiers are added to a Rate Table source. By adding tiers you are giving the Rate Table source explicit instructions about the values that should be mapped for inputs.
Resolution Types are instructions on handling the values between the tiers. Possible Resolution Types are:
- Do not give a value (all possible values must be provided)
- Interpolate between the closest tiers
- Find the nearest greater tier
- Find the nearest lower tier
Tiers and resolution types are explained in examples in the next section.
A Vehicle Risk Type has a Data Field called Mileage. This Data Field is of type Number.
We create a Rate Table to map mileage to a base rate. Since mileage is a Number input (and we can't gather the possible options automatically) we'll need to enter tiers into the Rate Table.
We enter the tiers 0, 50000, and 100000. We also fill out the final
rate column. Here's what the Rate Table looks like now:
Finally, we need to add a Resolution Type to our mileage source. This informs the Rate Table of how to handle the values between our tiers.
If we use the Do not give a value (all possible values must be provided) Resolution Type then the user will need to enter 0, 50000, or 100000 exactly into the mileage field. If they enter anything other than those 3 options then the rating engine will raise an error when attempting to resolve the Rate Table.
If we use the Find the nearest lower tier then the rating engine will take the mileage input and round it down to find the appropriate tier. If the user entered 25,000 then that rounds down to 0 and the rate will be 100. If the user enters 200,000 then that rounds down to 100,000 and the rate will be 300.
Find the nearest greater tier works the same as Find the nearest lower tier except that it rounds up instead of down.
If we use Interpolate between the closest tiers then the rating engine will take the mileage input and figure out where it is between two tiers. It will then apply that same distance to the rate that it resolves to.
For example, the user enters a mileage of 25,000. This is exactly between the 0 and 50,000 tiers. Therefore, this will map to a rate of 150 (exactly between 100 and 200).
Calculations use Fields, Rate Tables, and other Calculations to determine premiums, limits, and deductibles for an Item.
Calculations can be attached to a Risk Type or to an Item. If they are attached to the Risk Type then they are called Shared Calculations because all other Item Calculations can use their result. If they are attached to the Item then they are called Item Calculations.
Calculations are written in a syntax that is similar to Python 3. There are a few subtle differences in the Python syntax, however:
- All number literals are of type
- Multi-line blocks are not supported (since calculations are written one line at a time).
- Imports are not supported.
Much more on Calculations can be found in the Rating documentation.
Items are the coverages, fees and endorsement forms attached to a Risk.
When defining an Item the type and presence must be selected.
# Item Type
There are 3 item types available for selection:
# Associated Items for Endorsement Forms
When creating an Item of type Endorsement the
Associated Items field will be displayed.
Associated Items field is a multi-select list that includes all other
Fee type items that have been defined. The user will be required to associate at least one Item to any given Endorsement.
Note that users will not be allowed to delete an Item that is the only associated Item on an Endorsement. A message will display to the user indicating that the Endorsement must first be amended prior to deleting the item.
# Item presence
When defining an Item you must indicate if that Item is
optional. This is called the Item's presence.
Mandatory items of type
Fee are always selected on the Risk. Mandatory items of type
Endorsement are selected when one or more of the associated items is attached, they cannot be unselected.
Default items are selected by default when quoting but they can be unchecked. Default items of type
Endorsement will display and be selected by default when one or more of the associated items is attached.
Optional items are unselected by default when quoting but they can be checked. Optional items of type
Endorsement are displayed and available for selection when one or more associated items have been selected. If all of the associated items on an Optional Endorsement are removed the Endorsement is also removed and no longer available for selection.
Items can have multiple limits, each with one of the following types: Per Risk, Per Occurrence, or Policy Aggregate.
# Per Risk Limit
Per Risk Limit is for a specific risk like a car or building, or more general like a “per person” limit, grouping all people together.
# Example 1:
Towing and Labor Per Risk Limit: $600 Claim Amount: $750
Due to the coverage limit of $600, $150 will not be paid.
# Example 2:
Rental Reimbursement Per Risk Limit: $100 per day maximum 30 days Claim Amount: 5 Days of rental at $300 a day, Total: $1,500
Due to the coverage limit of $100 per day, only $500 will be covered.
# Per Occurrence Limit
Per Occurrence Limit refers to the total amount the insurance company will pay per incident during the policy term. Per Occurrence Limits are subject to the Aggregate limit.
Bodily Injury Per Occurrence Limit: $50,000 Claims: Person 1 Injured : $25,000 Person 2 injured : $25,000 Auto Damage : $25,000
Due to the limit of $50,000 there is $25,000 of claims that will not be covered under this policy.
# Policy Aggregate Limit
Policy Aggregate Limit is the maximum amount an insurer will pay for covered losses during a policy period.
Policy Aggregate limit: $200,000 Claims: Bodily Injury Per Occurrence Limit: $100,000 Medical Payments Per Occurrence Limit: $10,000 Personal Injury Per Occurrence Limit: $100,000 Fire Legal Per Occurrence Limit: $50,000 Total: $260,000
Due to the Aggregate limit the most that will be paid in this case is $200,000.