.. _product-configuration:

======================
Product Configuration
======================

This guide explains how to configure insurance products in the tiger Rating Engine, including setting up rating factors, tables, formulas, and managing product versions.

.. contents:: Table of Contents
   :local:
   :depth: 2

Overview
========

Product configuration involves four main components:

1. **Products**: Define insurance lines (BOP, Auto, etc.)
2. **Rating Factors**: Input variables for calculations
3. **Rating Tables**: Multi-dimensional rate lookups
4. **Formulas**: Calculation logic and rules

.. figure:: _static/screenshots/product_config_overview.png
   :alt: Product Configuration Overview
   :align: center
   :width: 100%

   *Screenshot Placeholder: Admin dashboard showing four tiles - Products (3 active), Rating Factors (45 total), Rating Tables (12 active), Formulas (38 configured) with "Configure" buttons*

Accessing Configuration
=======================

Admin Interface
---------------

.. figure:: _static/screenshots/admin_login.png
   :alt: Admin Interface Login
   :align: center
   :width: 60%

   *Screenshot Placeholder: Django admin login page with username/password fields and "Log in" button*

Access the admin interface:

1. Navigate to ``/admin/``
2. Log in with admin credentials
3. See the Rating section in the sidebar

.. note::
   Only users with Product Manager or Administrator roles can access configuration.

Navigation Structure
--------------------

.. figure:: _static/screenshots/admin_navigation.png
   :alt: Admin Navigation
   :align: center
   :width: 100%

   *Screenshot Placeholder: Admin sidebar showing Rating section expanded with Products, Rating Factors, Rating Tables, Rating Table Values, Formulas, Rating Runs, and Rating Coverages*

Admin sections:

* **Products**: Main product definitions
* **Rating Factors**: Input field configurations
* **Rating Tables**: Rate lookup tables
* **Rating Table Values**: Individual table entries
* **Formulas**: Calculation logic
* **Rating Runs**: Calculation history (read-only)
* **Rating Coverages**: Coverage results (read-only)

Creating a New Product
=======================

Step 1: Product Definition
---------------------------

.. figure:: _static/screenshots/new_product_form.png
   :alt: New Product Form
   :align: center
   :width: 100%

   *Screenshot Placeholder: Product creation form with fields for Product Code, Product Name, Description, Effective Date, End Date (optional), Is Active checkbox*

To create a new product:

1. Click **Products** → **Add Product**
2. Fill in required fields:

   .. code-block:: text

      Product Code: GL_POLICY
      Product Name: General Liability Insurance
      Description: Comprehensive general liability coverage for businesses
      Effective Date: 2025-02-01
      End Date: [Leave blank for no expiration]
      ☑ Is Active

3. Click **Save and continue editing**

Step 2: Product Settings
------------------------

.. figure:: _static/screenshots/product_settings_tab.png
   :alt: Product Settings
   :align: center
   :width: 100%

   *Screenshot Placeholder: Product settings tab showing Configuration section with Base Premium, Min Premium, Max Premium, and Options section with checkboxes*

Configure product settings:

* **Base Premium**: Starting calculation point
* **Minimum Premium**: Floor value
* **Maximum Premium**: Ceiling value
* **Options**: Special features or rules

Setting Up Rating Factors
=========================

Understanding Factor Types
--------------------------

.. figure:: _static/screenshots/factor_types_grid.png
   :alt: Rating Factor Types
   :align: center
   :width: 100%

   *Screenshot Placeholder: Grid showing different factor types with examples - Text (territory), Decimal (building_value), Integer (employees), Choice (class_code), Boolean (sprinklers), Date (prior_claims_date)*

Factor types available:

.. table:: Rating Factor Data Types
   :widths: 15 35 50

   +-----------+--------------------------------+----------------------------------------+
   | Type      | Use Case                       | Example                                |
   +===========+================================+========================================+
   | Text      | Codes, identifiers             | Territory: "001", Class: "RETAIL"     |
   +-----------+--------------------------------+----------------------------------------+
   | Decimal   | Monetary values, percentages   | Building Value: 500000.00              |
   +-----------+--------------------------------+----------------------------------------+
   | Integer   | Counts, whole numbers          | Number of Employees: 25                |
   +-----------+--------------------------------+----------------------------------------+
   | Choice    | Predefined options             | Building Class: A, B, C, D             |
   +-----------+--------------------------------+----------------------------------------+
   | Boolean   | Yes/No flags                   | Has Sprinklers: True/False             |
   +-----------+--------------------------------+----------------------------------------+
   | Date      | Dates, periods                 | Policy Effective Date: 2025-02-01      |
   +-----------+--------------------------------+----------------------------------------+

Creating a Rating Factor
------------------------

.. figure:: _static/screenshots/create_rating_factor.png
   :alt: Create Rating Factor
   :align: center
   :width: 100%

   *Screenshot Placeholder: Rating factor creation form with all fields and validation rules section*

To create a factor:

1. Navigate to **Rating Factors** → **Add Rating Factor**
2. Complete the form:

   .. code-block:: text

      Basic Information:
      ├── Product: [Select Product]
      ├── Factor Code: building_sqft
      ├── Factor Name: Building Square Footage
      └── Description: Total square footage of insured building

      Configuration:
      ├── Data Type: Decimal
      ├── Required: ☑
      └── Default Value: [Leave blank or set default]

      Validation Rules:
      ├── Minimum Value: 500
      ├── Maximum Value: 1000000
      └── Decimal Places: 0

3. Click **Save**

Factor Validation Rules
-----------------------

.. figure:: _static/screenshots/factor_validation_rules.png
   :alt: Factor Validation Rules
   :align: center
   :width: 100%

   *Screenshot Placeholder: Validation rules section showing different rule types - Required checkbox, Min/Max values, Regex pattern, Allowed choices list*

Configure validation:

* **Required Field**: Must be provided
* **Min/Max Values**: Numeric boundaries
* **Pattern Matching**: Regex for text fields
* **Choice Lists**: Predefined valid options
* **Custom Rules**: Python expressions

Managing Choice Lists
---------------------

.. figure:: _static/screenshots/choice_list_management.png
   :alt: Choice List Management
   :align: center
   :width: 100%

   *Screenshot Placeholder: Choice list editor showing table with Value, Display Name, Sort Order columns and Add/Remove buttons*

For choice fields:

.. code-block:: text

   Building Class Options:
   ├── A | Fire Resistive        | Sort: 1
   ├── B | Joisted Masonry        | Sort: 2
   ├── C | Non-Combustible        | Sort: 3
   ├── D | Frame Construction      | Sort: 4
   └── E | Mixed Construction      | Sort: 5

Creating Rating Tables
======================

Table Structure
---------------

.. figure:: _static/screenshots/rating_table_structure.png
   :alt: Rating Table Structure
   :align: center
   :width: 100%

   *Screenshot Placeholder: Visual representation of a 3D rating table with Territory on X-axis, Building Class on Y-axis, and Protection Class on Z-axis*

Rating tables support:

* **Multiple Dimensions**: Up to 10 factors
* **Date Versioning**: Different rates over time
* **Interpolation**: Calculate between points
* **Default Values**: Fallback rates

Step 1: Define Table
--------------------

.. figure:: _static/screenshots/create_rating_table.png
   :alt: Create Rating Table
   :align: center
   :width: 100%

   *Screenshot Placeholder: Table creation form with fields for Table Code, Name, Description, Product selection, and Dimensions configuration*

Create a new table:

1. Go to **Rating Tables** → **Add Rating Table**
2. Enter basic information:

   .. code-block:: text

      Table Definition:
      ├── Table Code: GL_BASE_RATES
      ├── Table Name: General Liability Base Rates
      ├── Description: Base rates by territory and class
      └── Product: General Liability Insurance

3. Configure dimensions

Step 2: Configure Dimensions
-----------------------------

.. figure:: _static/screenshots/table_dimensions_config.png
   :alt: Table Dimensions Configuration
   :align: center
   :width: 100%

   *Screenshot Placeholder: Dimensions section with add button and list showing Dimension 1: Territory (factor dropdown), Dimension 2: Business Class (factor dropdown)*

Add table dimensions:

.. code-block:: text

   Dimension Configuration:
   ├── Dimension 1:
   │   ├── Factor: territory
   │   └── Type: Exact Match
   ├── Dimension 2:
   │   ├── Factor: business_class
   │   └── Type: Exact Match
   └── Dimension 3:
       ├── Factor: protection_class
       └── Type: Range/Interpolate

Step 3: Enter Table Values
---------------------------

.. figure:: _static/screenshots/table_values_entry.png
   :alt: Table Values Entry
   :align: center
   :width: 100%

   *Screenshot Placeholder: Django admin page showing "Rating table values" list with columns for Table, Dimensions (JSON), Rate Value, Effective Date, and action buttons (Add, Import CSV, Generate Permutations)*

Enter rate values:

**Method 1: Manual Entry**

.. figure:: _static/screenshots/manual_table_entry.png
   :alt: Manual Table Entry
   :align: center
   :width: 80%

   *Screenshot Placeholder: Individual value entry form with dimension values and rate field*

1. Click **Add Table Value**
2. Select dimension values
3. Enter rate value
4. Set effective date

**Method 2: Bulk Import**

.. figure:: _static/screenshots/bulk_import_table.png
   :alt: Bulk Import Table Values
   :align: center
   :width: 100%

   *Screenshot Placeholder: CSV upload interface with template download link and file upload area*

1. Download CSV template
2. Fill with values
3. Upload CSV file
4. Review and confirm

**Method 3: Auto-Generate Permutations**

.. figure:: _static/screenshots/auto_generate_permutations.png
   :alt: Auto-Generate Permutations
   :align: center
   :width: 100%

   *Screenshot Placeholder: Auto-generate dialog with dimension value selections and default rate field*

1. Click **Generate Permutations**
2. Select values for each dimension
3. Set default rate
4. System creates all combinations

Table Value Management
----------------------

.. figure:: _static/screenshots/table_value_management.png
   :alt: Table Value Management
   :align: center
   :width: 100%

   *Screenshot Placeholder: Table values list with filters, search, bulk actions, and inline editing*

Manage values:

* **Filter**: By dimension values
* **Search**: Find specific rates
* **Bulk Edit**: Update multiple values
* **Version History**: Track changes
* **Export**: Download to Excel

Creating Formulas
=================

Formula Types
-------------

.. figure:: _static/screenshots/formula_types_comparison.png
   :alt: Formula Types Comparison
   :align: center
   :width: 100%

   *Screenshot Placeholder: Three panels showing Python Expression example, Table Lookup example, and Factor Multiply example with syntax*

Three formula types:

1. **Python Expression**

   .. code-block:: python

      # Calculate property premium
      base_rate * (building_value / 100) * territory_factor

2. **Table Lookup**

   .. code-block:: text

      Table: GL_BASE_RATES
      Lookup: territory, business_class
      Result: Store in 'base_rate'

3. **Factor Multiply**

   .. code-block:: text

      Factors: base_premium, territory_mod, class_mod, safety_credit
      Operation: Multiply all values
      Result: final_premium

Creating a Python Expression Formula
-------------------------------------

.. figure:: _static/screenshots/create_python_formula.png
   :alt: Create Python Formula
   :align: center
   :width: 100%

   *Screenshot Placeholder: Formula creation form with code editor showing syntax highlighting and available variables sidebar*

Steps:

1. Navigate to **Formulas** → **Add Formula**
2. Select **Python Expression** type
3. Enter formula details:

   .. code-block:: text

      Basic Information:
      ├── Product: General Liability Insurance
      ├── Formula Code: CALC_BASE_PREMIUM
      ├── Formula Name: Calculate Base Premium
      └── Description: Calculates base premium from limits

      Expression:
      ├── Expression: liability_limit * 0.001 * base_rate_factor
      ├── Result Variable: base_premium
      └── Execution Order: 1

4. Configure safety settings:

   .. code-block:: text

      Safety Settings:
      ├── ☑ Validate expression syntax
      ├── ☑ Restrict to safe functions
      ├── ☑ Log execution details
      └── Timeout: 1000ms

Creating a Table Lookup Formula
--------------------------------

.. figure:: _static/screenshots/create_table_formula.png
   :alt: Create Table Lookup Formula
   :align: center
   :width: 100%

   *Screenshot Placeholder: Table lookup formula form with table selection dropdown and dimension mapping fields*

Configure table lookup:

1. Select **Table Lookup** type
2. Configure lookup:

   .. code-block:: text

      Table Configuration:
      ├── Table: GL_BASE_RATES
      ├── Effective Date: Use run effective date
      └── Result Variable: base_rate

      Dimension Mapping:
      ├── Territory: Map to 'territory' factor
      ├── Business Class: Map to 'business_class' factor
      └── Protection: Map to 'protection_class' factor

      Options:
      ├── ☑ Use interpolation if available
      ├── ☑ Use default if no match
      └── Default Value: 1.0

Formula Dependencies
--------------------

.. figure:: _static/screenshots/formula_dependencies.png
   :alt: Formula Dependencies
   :align: center
   :width: 100%

   *Screenshot Placeholder: Dependency graph showing formulas as nodes with arrows indicating execution order and dependencies*

Managing dependencies:

* **Execution Order**: Sequential processing
* **Variable Dependencies**: Required inputs
* **Conditional Execution**: Based on factors
* **Parallel Execution**: Independent formulas

Testing Formulas
----------------

.. figure:: _static/screenshots/formula_testing.png
   :alt: Formula Testing Interface
   :align: center
   :width: 100%

   *Screenshot Placeholder: Test interface with input values on left, Execute button, and results panel on right showing calculated value and execution log*

Test your formulas:

1. Click **Test Formula**
2. Enter sample values
3. Execute calculation
4. Review results and logs

Managing Product Versions
=========================

Version Control
---------------

.. figure:: _static/screenshots/product_versioning.png
   :alt: Product Version Control
   :align: center
   :width: 100%

   *Screenshot Placeholder: Version timeline showing Product V1 (Jan 2024), V2 (Jul 2024), V3 (Jan 2025) with changes listed*

Version management:

* **Effective Dates**: When changes take effect
* **Change Tracking**: What was modified
* **Parallel Versions**: Multiple active versions
* **Version History**: Complete audit trail

Creating a New Version
----------------------

.. figure:: _static/screenshots/create_product_version.png
   :alt: Create Product Version
   :align: center
   :width: 100%

   *Screenshot Placeholder: Version creation dialog with options to copy existing product, modify specific components, and set effective date*

To create a version:

1. Select existing product
2. Click **Create Version**
3. Choose what to copy:
   * All configurations
   * Specific components
   * Structure only
4. Set effective date
5. Make modifications

Rate Changes
------------

.. figure:: _static/screenshots/rate_change_workflow.png
   :alt: Rate Change Workflow
   :align: center
   :width: 100%

   *Screenshot Placeholder: Rate change interface showing current rates, proposed rates, percentage change, and approval workflow*

Implementing rate changes:

1. **Create Draft**: New table values
2. **Review Changes**: Compare old vs new
3. **Set Effective Date**: When changes apply
4. **Approve**: Management approval
5. **Activate**: Make live

Best Practices
==============

Naming Conventions
------------------

Use consistent naming:

.. code-block:: text

   Products:
   ├── Code: PRODUCT_TYPE (e.g., GL_POLICY, BOP_STANDARD)
   └── Name: Descriptive name with version

   Factors:
   ├── Code: lowercase_underscore (e.g., building_value, territory_code)
   └── Name: Title Case Description

   Tables:
   ├── Code: PRODUCT_TABLE_PURPOSE (e.g., GL_BASE_RATES)
   └── Name: Clear description of contents

   Formulas:
   ├── Code: ACTION_TARGET (e.g., CALC_BASE_PREMIUM)
   └── Name: Verb + Object

Documentation
-------------

Document everything:

* **Product Description**: Purpose and coverage
* **Factor Help Text**: Guide users
* **Table Notes**: Explain rate basis
* **Formula Comments**: Calculation logic

Testing Strategy
----------------

.. figure:: _static/screenshots/testing_checklist.png
   :alt: Testing Checklist
   :align: center
   :width: 100%

   *Screenshot Placeholder: Testing checklist with sections for Unit Tests, Integration Tests, Edge Cases, and User Acceptance*

Test thoroughly:

.. code-block:: text

   Testing Checklist:
   ☐ Individual formula validation
   ☐ Complete calculation flow
   ☐ Edge cases (min/max values)
   ☐ Missing data handling
   ☐ Date-based versioning
   ☐ Performance under load
   ☐ User acceptance testing

Change Management
-----------------

For production changes:

1. **Development Environment**: Initial setup
2. **Testing Environment**: Validate changes
3. **UAT Environment**: User testing
4. **Production**: Scheduled deployment
5. **Rollback Plan**: If issues arise

Common Configuration Scenarios
===============================

Multi-State Product
-------------------

.. figure:: _static/screenshots/multi_state_config.png
   :alt: Multi-State Configuration
   :align: center
   :width: 100%

   *Screenshot Placeholder: Configuration showing state-specific tables and rules with tabs for each state*

Configure for multiple states:

1. Create state-specific tables
2. Add state factor to product
3. Use conditional formulas
4. Set state-specific rules

Tiered Rating
-------------

.. figure:: _static/screenshots/tiered_rating_setup.png
   :alt: Tiered Rating Setup
   :align: center
   :width: 100%

   *Screenshot Placeholder: Tiered structure showing Bronze/Silver/Gold tiers with different rates and limits*

Implement tiers:

1. Define tier factor
2. Create tier-based tables
3. Add tier modifiers
4. Configure tier benefits

Package Policies
----------------

.. figure:: _static/screenshots/package_policy_config.png
   :alt: Package Policy Configuration
   :align: center
   :width: 100%

   *Screenshot Placeholder: Package configuration showing multiple coverages bundled with package discounts*

Bundle coverages:

1. Create parent product
2. Define component coverages
3. Add package discounts
4. Configure dependencies

Troubleshooting
===============

Common Issues
-------------

.. table:: Configuration Troubleshooting
   :widths: 30 70

   +----------------------------+-----------------------------------------------+
   | Issue                      | Solution                                      |
   +============================+===============================================+
   | Formula won't save         | Check Python syntax, ensure variables exist  |
   +----------------------------+-----------------------------------------------+
   | Table lookup fails         | Verify dimension mapping, check values exist |
   +----------------------------+-----------------------------------------------+
   | Calculation incorrect      | Review execution order, check dependencies   |
   +----------------------------+-----------------------------------------------+
   | Version conflict           | Ensure effective dates don't overlap         |
   +----------------------------+-----------------------------------------------+
   | Performance issues         | Optimize formulas, index table lookups       |
   +----------------------------+-----------------------------------------------+

Validation Tools
----------------

.. figure:: _static/screenshots/validation_tools.png
   :alt: Configuration Validation Tools
   :align: center
   :width: 100%

   *Screenshot Placeholder: Validation dashboard showing checkmarks and warnings for different configuration components*

Use built-in validators:

* **Product Validator**: Checks completeness
* **Formula Validator**: Syntax and logic
* **Table Validator**: Data consistency
* **Integration Test**: End-to-end validation

Next Steps
==========

* **Perform Calculations**: :doc:`performing_calculations`
* **Real Example**: :doc:`real_world_scenario`
* **API Setup**: :doc:`api_integration`
* **User Guide**: :doc:`user_guide`

.. warning::
   Always test configuration changes in a non-production environment before deploying to live systems.

.. tip::
   Use the product copy feature to create similar products quickly, then modify as needed.