.. _bulk-rating: ============= Bulk Rating ============= The Bulk Rating System allows you to process hundreds or thousands of insurance premium calculations simultaneously through CSV upload or API integration. This is ideal for portfolio analysis, renewal processing, or mass quoting. .. contents:: Table of Contents :local: :depth: 2 Overview ======== What is Bulk Rating? -------------------- .. figure:: _static/screenshots/bulk_rating_overview.png :alt: Bulk Rating Overview :align: center :width: 100% *Screenshot Placeholder: Dashboard showing bulk rating jobs with status (completed, processing, queued), progress bars, and results summary* Bulk Rating enables you to: * Process 100s to 1000s of quotes in a single batch * Upload rating requests via CSV file * Submit via REST API for system integration * Monitor real-time progress * Download comprehensive results * Receive webhook notifications when complete Key Features ------------ .. table:: Bulk Rating Features :widths: 30 70 +---------------------------+------------------------------------------------------------+ | Feature | Description | +===========================+============================================================+ | High Volume Processing | Handle 1000s of ratings per job | +---------------------------+------------------------------------------------------------+ | CSV Upload | Simple spreadsheet-based submission | +---------------------------+------------------------------------------------------------+ | API Integration | Programmatic submission and retrieval | +---------------------------+------------------------------------------------------------+ | Real-Time Progress | Live updates as ratings complete | +---------------------------+------------------------------------------------------------+ | Error Handling | Detailed error logs for failed ratings | +---------------------------+------------------------------------------------------------+ | Webhook Notifications | Get notified when jobs finish | +---------------------------+------------------------------------------------------------+ | Result Export | Download results in CSV or JSON | +---------------------------+------------------------------------------------------------+ | Performance Optimized | Cached data for faster processing | +---------------------------+------------------------------------------------------------+ When to Use Bulk Rating ------------------------ Use bulk rating for: * **Portfolio Renewals**: Rate entire portfolio at renewal * **Market Analysis**: Compare pricing across segments * **Data Migration**: Import historical ratings * **Batch Quoting**: Process overnight quote requests * **System Integration**: Connect to policy management systems * **Testing**: Validate product configurations at scale Getting Started =============== Accessing Bulk Rating ---------------------- .. figure:: _static/screenshots/bulk_rating_access.png :alt: Access Bulk Rating :align: center :width: 100% *Screenshot Placeholder: Main navigation showing "Bulk Rating" menu item highlighted, with submenu showing Upload, Jobs, API Docs* Access bulk rating: 1. Click **Bulk Rating** in main menu 2. Choose your method: * **Upload CSV** - File-based submission * **API Submit** - Programmatic submission * **View Jobs** - Monitor and download results Permissions Required -------------------- .. table:: Bulk Rating Permissions :widths: 25 75 +------------------+-----------------------------------------------------------+ | Role | Access | +==================+===========================================================+ | Viewer | No access | +------------------+-----------------------------------------------------------+ | Underwriter | No access | +------------------+-----------------------------------------------------------+ | Product Manager | Full access (upload, monitor, download) | +------------------+-----------------------------------------------------------+ | Administrator | Full access + manage all users' jobs | +------------------+-----------------------------------------------------------+ .. warning:: Bulk rating is a powerful feature. Only users with Product Manager or Administrator roles can access it. Using CSV Upload ================ Step 1: Prepare Your CSV File ------------------------------ .. figure:: _static/screenshots/csv_template.png :alt: CSV Template :align: center :width: 100% *Screenshot Placeholder: Excel showing CSV template with column headers and sample data rows* Download the CSV template: 1. Navigate to **Bulk Rating** → **Upload** 2. Click **Download Template** 3. Choose product (e.g., "BOP Template") 4. Open in Excel or Google Sheets CSV Format ---------- Required columns: .. code-block:: text product_code,effective_date,external_reference,territory,class_code,... Example BOP template: .. csv-table:: BOP Rating Template :header: "product_code", "effective_date", "external_reference", "territory", "class_code", "building_value", "building_class" :widths: 15, 15, 20, 10, 15, 15, 10 "BOP", "2025-01-01", "POL-001", "01", "43211", "500000", "B" "BOP", "2025-01-01", "POL-002", "14", "47221", "750000", "A" "BOP", "2025-01-01", "POL-003", "02", "43211", "1000000", "B" Coverage columns (add for each coverage): .. code-block:: text coverage_1_code,coverage_1_limit,coverage_1_deductible coverage_2_code,coverage_2_limit,coverage_2_deductible Example with coverages: .. csv-table:: BOP with Coverages :header: "product_code", "territory", "building_value", "cov_1_code", "cov_1_limit", "cov_1_deductible" :widths: 15, 10, 15, 15, 15, 15 "BOP", "01", "500000", "BLDG", "500000", "1000" "BOP", "14", "750000", "BLDG", "750000", "5000" Step 2: Fill In Your Data -------------------------- .. figure:: _static/screenshots/csv_data_entry.png :alt: CSV Data Entry :align: center :width: 100% *Screenshot Placeholder: Excel showing filled CSV with multiple rows of rating data* Data entry tips: * **One row per rating**: Each row is one premium calculation * **Required fields**: Must be filled (marked in template) * **Optional fields**: Can be left blank * **Consistent format**: Dates as YYYY-MM-DD, numbers without commas * **External reference**: Your own tracking number * **No formulas**: Enter values directly, not Excel formulas Common data types: .. table:: CSV Data Types :widths: 20 30 50 +----------------+------------------------+----------------------------------+ | Field Type | Format | Example | +================+========================+==================================+ | Product Code | Text | BOP, GL_POLICY, WC | +----------------+------------------------+----------------------------------+ | Date | YYYY-MM-DD | 2025-01-17 | +----------------+------------------------+----------------------------------+ | Currency | Number (no $, no ,) | 500000 (not $500,000) | +----------------+------------------------+----------------------------------+ | Percentage | Decimal | 0.15 (not 15%) | +----------------+------------------------+----------------------------------+ | Territory | Text/Number | 01, 14, NY | +----------------+------------------------+----------------------------------+ | Yes/No | true/false or 1/0 | true, false, 1, 0 | +----------------+------------------------+----------------------------------+ Step 3: Upload Your File ------------------------- .. figure:: _static/screenshots/csv_upload_interface.png :alt: CSV Upload Interface :align: center :width: 100% *Screenshot Placeholder: Upload form with drag-drop area, file selector, optional fields for job name and webhook URL* Upload your CSV: 1. Go to **Bulk Rating** → **Upload** 2. Drag-and-drop CSV file or click **Choose File** 3. Optional: Enter job name (e.g., "Q1 2025 Renewals") 4. Optional: Add webhook URL for notifications 5. Click **Upload and Process** Upload validation: .. code-block:: text ✓ File uploaded: renewals_q1.csv ✓ Size: 2.4 MB ✓ Detected: 1,247 rating requests ✓ Product: BOP ✓ Format: Valid Processing started... Job ID: JOB-2025-01-17-001 Step 4: Monitor Progress ------------------------- .. figure:: _static/screenshots/bulk_job_progress.png :alt: Job Progress Monitoring :align: center :width: 100% *Screenshot Placeholder: Progress page showing real-time updates - progress bar, statistics (1247 total, 856 completed, 823 success, 33 errors), estimated time remaining* After upload, monitor progress: * **Progress Bar**: Visual completion percentage * **Statistics**: Total, completed, success, errors * **Status**: Queued → Processing → Completed * **Estimated Time**: Time remaining * **Error Count**: Failed ratings (click to view details) * **Auto-Refresh**: Page updates every 5 seconds Example progress display: .. code-block:: text Job: Q1 2025 Renewals Status: Processing Progress: 856 of 1,247 (68.6%) Statistics: ├── Total requests: 1,247 ├── Completed: 856 ├── Success: 823 └── Errors: 33 Estimated time remaining: 2 minutes [████████████████████░░░░░░░░░░] 68.6% Step 5: Download Results ------------------------- .. figure:: _static/screenshots/bulk_results_download.png :alt: Download Results :align: center :width: 100% *Screenshot Placeholder: Completed job showing download options - CSV, JSON, Error Log, with summary statistics* When complete, download results: 1. Job status changes to "Completed" 2. Download options appear: * **Download CSV**: Results in spreadsheet format * **Download JSON**: Results in JSON format * **Download Error Log**: Details of failed ratings * **View Summary**: Quick statistics view Result CSV format: .. csv-table:: Results CSV :header: "external_reference", "status", "total_premium", "coverage_1_premium", "coverage_2_premium", "errors" :widths: 20, 10, 15, 20, 20, 15 "POL-001", "success", "2340.00", "1200.00", "1140.00", "" "POL-002", "success", "2847.00", "1320.00", "1527.00", "" "POL-003", "error", "", "", "", "Invalid territory code" Using the API ============= API Overview ------------ .. figure:: _static/screenshots/bulk_api_flow.png :alt: Bulk API Flow :align: center :width: 100% *Screenshot Placeholder: Flow diagram showing Submit Job → Poll Status → Download Results with API endpoints* API workflow: 1. **Submit Job**: POST bulk rating requests 2. **Get Job Status**: Poll for completion 3. **Download Results**: Retrieve calculated premiums 4. **Optional**: Set up webhooks for notifications API Endpoint ------------ Base URL: ``https://api.tigerrating.com/v1/rating/`` **Synchronous (up to 100 requests)**: .. code-block:: bash POST /rating/bulk-calculate/sync/ **Asynchronous (100+ requests)**: .. code-block:: bash POST /rating/bulk-calculate/async/ Synchronous Bulk Rating ------------------------ For smaller batches (≤100 requests), get immediate results: **Request:** .. code-block:: bash curl -X POST https://api.tigerrating.com/v1/rating/bulk-calculate/sync/ \ -H "Authorization: Token YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "requests": [ { "product_code": "BOP", "effective_date": "2025-01-17", "external_reference": "POL-001", "risk_characteristics": { "territory": "01", "class_code": "43211", "building_value": 500000 }, "coverages": [ { "coverage_code": "BLDG", "limit": 500000, "deductible": 1000 } ] }, { "product_code": "BOP", "external_reference": "POL-002", ... } ] }' **Response:** .. code-block:: json { "success": true, "total": 2, "success_count": 2, "error_count": 0, "results": [ { "external_reference": "POL-001", "status": "success", "total_premium": 2340.00, "coverages": [ { "coverage_code": "BLDG", "premium": 1200.00 }, { "coverage_code": "GL", "premium": 1140.00 } ] }, { "external_reference": "POL-002", "status": "success", "total_premium": 2847.00, ... } ] } Asynchronous Bulk Rating ------------------------- For larger batches (>100 requests), use async processing: **Step 1: Submit Job** .. code-block:: bash curl -X POST https://api.tigerrating.com/v1/rating/bulk-calculate/async/ \ -H "Authorization: Token YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "job_name": "Q1 Renewals", "webhook_url": "https://yourapp.com/webhooks/bulk-complete", "requests": [ {...}, {...}, ... // up to 10,000 requests ] }' **Response:** .. code-block:: json { "success": true, "job_id": "JOB-2025-01-17-001", "status": "queued", "total_requests": 1247, "estimated_completion": "2025-01-17T15:30:00Z", "status_url": "/rating/bulk-jobs/JOB-2025-01-17-001/", "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/" } **Step 2: Poll Status** .. code-block:: bash curl -X GET https://api.tigerrating.com/v1/rating/bulk-jobs/JOB-2025-01-17-001/ \ -H "Authorization: Token YOUR_TOKEN" **Response (Processing):** .. code-block:: json { "job_id": "JOB-2025-01-17-001", "status": "processing", "total_requests": 1247, "completed_count": 856, "success_count": 823, "error_count": 33, "progress_percentage": 68.6, "created_at": "2025-01-17T15:20:00Z", "started_at": "2025-01-17T15:20:15Z", "estimated_completion": "2025-01-17T15:22:00Z" } **Response (Completed):** .. code-block:: json { "job_id": "JOB-2025-01-17-001", "status": "completed", "total_requests": 1247, "completed_count": 1247, "success_count": 1214, "error_count": 33, "progress_percentage": 100.0, "success_rate": 97.4, "created_at": "2025-01-17T15:20:00Z", "started_at": "2025-01-17T15:20:15Z", "completed_at": "2025-01-17T15:22:03Z", "execution_time_ms": 108000, "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/" } **Step 3: Download Results** .. code-block:: bash curl -X GET https://api.tigerrating.com/v1/rating/bulk-jobs/JOB-2025-01-17-001/results/ \ -H "Authorization: Token YOUR_TOKEN" **Response:** .. code-block:: json { "job_id": "JOB-2025-01-17-001", "total_results": 1247, "success_count": 1214, "error_count": 33, "results": [ { "external_reference": "POL-001", "status": "success", "rating_run_id": "RUN-123456", "total_premium": 2340.00, "coverages": [...] }, { "external_reference": "POL-002", "status": "error", "errors": ["Invalid territory code: 99"] }, ... ] } Webhook Notifications ---------------------- .. figure:: _static/screenshots/webhook_flow.png :alt: Webhook Notification Flow :align: center :width: 100% *Screenshot Placeholder: Flow showing job completion → webhook POST to your URL → your system processes notification* Set up webhooks for automatic notifications: **Webhook Payload (Job Complete):** .. code-block:: json { "event": "bulk_job.completed", "job_id": "JOB-2025-01-17-001", "status": "completed", "total_requests": 1247, "success_count": 1214, "error_count": 33, "success_rate": 97.4, "execution_time_ms": 108000, "completed_at": "2025-01-17T15:22:03Z", "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/", "signature": "sha256=abcdef123456..." } **Your Webhook Handler:** .. code-block:: python from django.http import JsonResponse from django.views.decorators.csrf import csrf_exempt import json @csrf_exempt def bulk_job_webhook(request): payload = json.loads(request.body) if payload['event'] == 'bulk_job.completed': job_id = payload['job_id'] success_rate = payload['success_rate'] # Process the notification download_and_process_results(job_id) # Send notification send_email(f"Bulk job {job_id} completed: {success_rate}% success") return JsonResponse({'status': 'received'}) Advanced Features ================= Job Management -------------- .. figure:: _static/screenshots/bulk_job_list.png :alt: Job Management List :align: center :width: 100% *Screenshot Placeholder: List of bulk jobs with filters (status, date), search, and action buttons (view, download, cancel)* Manage your bulk jobs: * **View All Jobs**: See history of all bulk rating jobs * **Filter**: By status (queued, processing, completed, failed) * **Search**: Find specific jobs by name or ID * **Cancel**: Stop processing jobs (only while queued or processing) * **Delete**: Remove old jobs and results * **Re-run**: Submit same data again Job retention: .. table:: Job Retention Policy :widths: 30 70 +---------------------+------------------------------------------------------------+ | Item | Retention | +=====================+============================================================+ | Job Metadata | 90 days | +---------------------+------------------------------------------------------------+ | Results | 90 days | +---------------------+------------------------------------------------------------+ | Error Logs | 90 days | +---------------------+------------------------------------------------------------+ .. tip:: Download and save results you need long-term. Jobs are automatically deleted after 90 days. Error Handling -------------- .. figure:: _static/screenshots/bulk_error_details.png :alt: Error Details :align: center :width: 100% *Screenshot Placeholder: Error log showing individual failed ratings with error messages and line numbers* Understanding errors: **Common Errors:** .. table:: Common Bulk Rating Errors :widths: 40 60 +--------------------------------+-----------------------------------------------+ | Error | Solution | +================================+===============================================+ | "Invalid product code" | Check product code matches available products | +--------------------------------+-----------------------------------------------+ | "Required field missing" | Fill in all required columns | +--------------------------------+-----------------------------------------------+ | "Territory not found" | Verify territory code is valid | +--------------------------------+-----------------------------------------------+ | "Value out of range" | Check min/max validation rules | +--------------------------------+-----------------------------------------------+ | "Invalid date format" | Use YYYY-MM-DD format | +--------------------------------+-----------------------------------------------+ | "Coverage code invalid" | Verify coverage is available for product | +--------------------------------+-----------------------------------------------+ **Error Log Format:** .. code-block:: text Line 45: POL-044 Error: Invalid territory code: '99' Details: Territory '99' not found in table TERRITORY_CODES Resolution: Use valid territory code (01-50) Line 67: POL-066 Error: Building value out of range Details: Value 50000 below minimum 100000 Resolution: Increase building_value to at least 100000 Handling partial failures: 1. **Download error log**: See which ratings failed 2. **Fix errors**: Correct data in original CSV 3. **Re-upload**: Submit only the corrected rows 4. **Merge results**: Combine successful and corrected results Performance Optimization ------------------------ .. figure:: _static/screenshots/bulk_performance.png :alt: Performance Metrics :align: center :width: 100% *Screenshot Placeholder: Performance dashboard showing throughput (ratings/second), cache hit rate, average time per rating* The system is optimized for high-volume processing: * **Caching**: Product configurations cached (70-90% faster) * **Chunking**: Processes in batches to manage memory * **Parallel Processing**: Multiple ratings calculated simultaneously * **Database Optimization**: Minimized queries through batching Expected performance: .. table:: Processing Speed :widths: 20 40 40 +----------------+---------------------------+---------------------------+ | Batch Size | Processing Time | Throughput | +================+===========================+===========================+ | 100 ratings | 1-2 seconds | 50-100 ratings/sec | +----------------+---------------------------+---------------------------+ | 500 ratings | 5-10 seconds | 50-100 ratings/sec | +----------------+---------------------------+---------------------------+ | 1,000 ratings | 10-20 seconds | 50-100 ratings/sec | +----------------+---------------------------+---------------------------+ | 5,000 ratings | 50-100 seconds | 50-100 ratings/sec | +----------------+---------------------------+---------------------------+ | 10,000 ratings | 100-200 seconds | 50-100 ratings/sec | +----------------+---------------------------+---------------------------+ .. note:: Actual performance depends on product complexity, server load, and data characteristics. Best Practices ============== Data Preparation ---------------- 1. **Validate Before Upload**: * Check required fields are filled * Verify data formats match template * Remove test/invalid rows 2. **Use External References**: * Include your policy/quote numbers * Makes results easier to match back to your system * Helps with error tracking 3. **Batch Logically**: * Group by product type * Separate new business from renewals * Keep related risks together 4. **Test First**: * Upload small test batch (10-20 rows) * Verify results are correct * Then upload full batch Error Prevention ---------------- Common mistakes to avoid: .. code-block:: text ❌ Don't: Use different date formats (1/17/2025, Jan 17 2025) ✓ Do: Use consistent YYYY-MM-DD format (2025-01-17) ❌ Don't: Include $ signs or commas in numbers ($500,000) ✓ Do: Use plain numbers (500000) ❌ Don't: Use Excel formulas in CSV ✓ Do: Copy/paste values only ❌ Don't: Mix products in one job ✓ Do: Separate jobs by product type ❌ Don't: Upload without testing ✓ Do: Test with small batch first Integration Patterns -------------------- **Pattern 1: Nightly Renewal Processing** .. code-block:: python # Scheduled job (runs at midnight) def process_renewals(): # Get renewals expiring in 30 days renewals = get_expiring_policies(days=30) # Build bulk request requests = [build_rating_request(policy) for policy in renewals] # Submit bulk job job = submit_bulk_rating(requests, webhook_url=WEBHOOK_URL) # Webhook handler will process results when complete **Pattern 2: On-Demand Quote Generator** .. code-block:: python # API endpoint for quote requests def generate_quotes(quote_requests): if len(quote_requests) <= 100: # Synchronous for small batches results = bulk_rate_sync(quote_requests) return results else: # Asynchronous for large batches job = bulk_rate_async(quote_requests) return {"job_id": job.id, "status_url": job.status_url} **Pattern 3: Data Migration** .. code-block:: python # Migrate historical ratings def migrate_historical_data(): # Load from legacy system legacy_policies = load_legacy_policies() # Convert to bulk rating format requests = convert_to_rating_format(legacy_policies) # Process in chunks chunk_size = 1000 for chunk in chunks(requests, chunk_size): job = submit_bulk_rating(chunk) wait_for_completion(job) save_results(job) Troubleshooting =============== Upload Issues ------------- **Issue: "File too large"** * **Limit**: 50 MB per file * **Solution**: Split into multiple files * **Alternative**: Use API for very large batches **Issue: "Invalid CSV format"** * **Common Cause**: Extra columns, wrong encoding * **Solution**: Use the template, save as UTF-8 CSV * **Check**: Open in text editor to verify format Processing Issues ----------------- **Issue: Job stuck in "queued" status** * **Cause**: High server load, queue backup * **Solution**: Wait; jobs process in order * **Check**: Contact support if queued >15 minutes **Issue: High error rate (>10%)** * **Cause**: Data quality issues * **Solution**: Download error log, fix common errors * **Prevention**: Test with small batch first Result Issues ------------- **Issue: Results don't match expected premiums** * **Cause**: Effective date, territory, or factor mismatches * **Solution**: Compare input to individual rating, verify configuration * **Check**: Run a few ratings individually to debug **Issue: Missing results** * **Cause**: Job still processing or failed * **Solution**: Check job status, review error log * **Retry**: Can re-submit failed ratings API Issues ---------- **Issue: Authentication failures** .. code-block:: bash {"detail": "Authentication credentials were not provided."} * **Solution**: Include Authorization header with valid token * **Check**: Token hasn't expired **Issue: Rate limit exceeded** .. code-block:: bash {"detail": "Request was throttled."} * **Solution**: Reduce submission frequency * **Alternative**: Use async endpoint for large batches * **Contact**: Support to increase limits Next Steps ========== * **Try It**: Upload your first CSV file * **Learn More**: See :doc:`api_integration` for API details * **Optimize**: Read :doc:`performance_optimization` for best performance * **Automate**: Integrate with your systems .. tip:: Start small! Upload 10-20 test ratings first to validate your data format and understand the process. Then scale up to full batches. .. warning:: Always download and save results you need. Bulk jobs and results are automatically deleted after 90 days.