Introduction

The goal of this guide is to accelerate new Proposition Factory developer on-boarding by providing of information about how to build Digital Covers.

Proposition Factory uses Drools as underlying calculation and rule execution engine.

Key concepts

• Space - logical grouping of projects on per Organization or Whitelabel basis.
• Project - domain model, digital covers, propositions and underwriting rules.
• Domain model - objects insured, payment information as a set of Java classes representing objects necessary for calculation. In Athena the domain model is auto-generated so it isn’t necessary to maintain it manually.
• Factors - set of values in Drools Guided Tables to choose from depending on information which describes insured objects
• Drools workbench - web application allowing users to edit Drools rules trough friendly user interface. Drools workbench also provides “syntax sugar” functionality for developing Drools rules more effectively. Examples are rule templates, guided decision tables and excel-based decision tables.
• KIE Execution server - component what allows to deploy Drools projects as containers and provides easy to use REST API for triggering calculation logic. Execution server also supports hosting of multiple versions of same project in parallel which is beneficial for insurance calculation models.
• Knowledge base - The knowledge base is a repository of all the application’s knowledge definitions. It will contain rules, formulas, factors, data models. The knowledge base itself does not contain runtime data (i.e. exact Vehicle used for motor insurance premium calculation), instead sessions are created from the knowledge base in which data can be inserted and calculation process instances started.
• Knowledge session - the knowledge session is an instance of interaction with calculation engine. There are two types of knowledge sessions:
  • Stateful session where the engine holds all session related information until client explicitly cleans it.
  • Stateless session where the engine automatically cleans session related information after each calculation request.
• Working memory - set of objects available to rules project used for necessary calculations. Proposition Factory automatically generates these from user inputs and provides it to Drools when the calculation is executed.

Usage

Solution structure

Out Of the Box available Attribute Sets

• Domain model projects - contains data structures what are used in calculations done in cover and proposition objects such as person, vehicle, address, etc. These projects are autogenerated by Proposition Factory, but while you don’t need to manually maintain them, it is still good to be aware about them existing.
• Cover projects - segregates calculation of one to multiple insurance covers what will be used together in insurance propositions. These projects include calculation of all cover values such as premium, limits, deductibles and excesses as well as cover-specific underwriting rules where they must be enforced across all propositions which includes particular cover.
• Proposition projects - references all the covers necessary for particular insurance proposition and aggregates outputs of each individual solution
• Underwriting projects - helpful for the cases where multiple insurance propositions shares same underwriting logic what needs to be re-used.

Model development guidelines

General rules

Typical proposal calculation flow will be following:

While in general case for well designed cover projects it shouldn’t be mandatory to explicitly specify priority of each individual rule (Drools term - salience, the higher salience is, the sooner the rule will be executed), there are cases where it will be beneficial therefore suggestion is to define priority ranges used for each type of projects so that they don’t overlap in overall solution. Example could be:

• Validation - 300-400
• Underwriting - 200-300
• Formulas/factors - 100-200
• Summary calculation - 0-100

There should be knowledge base definition for each project where there is an abbition to execute the calculation against it (typically - all projects, but data model). Each knowledge base should explicitly define rule packages from the project to include (use * for all) and at least default stateless knowledge session named “ksession”. Naming convention for the default knowledge session - “{ProjectName}KieSession” Given that drools workbench allows to run test scenarios only against stateful knowledge sessions, for the projects where tests are used there should also be a definition of stateful sesssion.

“Domain model” projects

• Project name should be in PascalCase, prefixed with “Model” and followed by meaningful description (i.e. ModelUK).
• Naming of data structures and properties should follow Java naming guidelines. End user shouldn’t generally care about this as these structures are auto-generated.

“Underwriting” projects

• Project name should be in PascalCase, prefixed with “Underwriting” and followed by meaningful description (i.e. UnderwritingUKMotor).
• Underwriting projects are responsible for validation of input data and definition of underwriting rules. These projects are also responsible about calculation of any values necessary for the validation (for example calculation of person’s age based on given birth date).
• Information about validation and underwriting failures is exposed as a set of facts. Each validation or underwriting failure fact should be uniquely indentified.

“Cover” projects

• Project name should be in PascalCase, prefixed with “Cover” and followed by meaningful description of the cover (i.e. CoverVehicleTheft).
• Factor rules should be in PascalCase, prefixed with “{CoverName}Factor” and followed by meaningful description of the factor (i.e. CoverVehicleTheftFactorVehicleTransmission).
• Formula rules should be in PascalCase, prefixed with “{CoverName}Formula” and followed by meaningful description of the formula (i.e. CoverVehicleTheftFormulaSetBaseRate).
• Repetition of cover name in both cases above is necessary because at the end of the day rules for all covers under particular insurance solution will be executed in common “bucket” of rules, rules would conflict when named same across different cover projects.
• Cover projects are responsible for generating cover object(s) during it’s calculation. Cover object(s) created by the project should be each uniquely identified (for example by setting cover type field) and referenced by this type in further calculations in the scope of project. Risk of not doing so is other cover calculations picking up and amending these covers.

“Proposition” projects

• Project name should be in PascalCase, prefixed with “Proposition” and followed by meaningful description (i.e. PropositionMotorInsurance, PropositionTravelInsurance).
• Project should define dependencies to underwriting, cover and other proposition projects it includes both at the package level and knowledge base level.
• Proposition project is responsible for giving summary information on top of calculations done in dependant projects (i.e. calculation of total premium, calculation of any fees applicable to total premium, payment instalment plans and dates, etc.)