AutoBenefits

Overview

AutoApplyBenefitsTask automatically applies insurance benefits (copay, deductible, coinsurance, max out-of-pocket) to visits and quotes from eligibility transactions. It processes visits in batch mode, matching eligibility data with visit coverage using AutoBenefitsRule configurations to determine which benefits to apply.

Use this task when: You need to automatically populate insurance benefit amounts on visits and quotes from eligibility verification responses, using rule-based matching to handle multiple plans, service types, and facilities.

Don't use this task when:

• Manually entering benefits on a single visit (use the UI or real-time auto benefits instead)
• No eligibility transactions exist for visits (task requires ExternalAPI configuration and eligibility data)
• Processing visits without insurance configured with benefits API access

Parameters

Execution Flow

flowchart TD
    A[Start AutoApplyBenefitsTask] --> B[Get batch visits with new eligibility transactions]
    B --> C[Get all batch quotes]
    C --> D[Join visits to quotes]
    D --> E{Any visits?}
    E -->|No| Z[End]
    E -->|Yes| F[Filter visits to those with benefits API access]

    F --> G[For each visit]
    G --> H[For each visit coverage]
    H --> I{Coverage has benefits API?}
    I -->|No| N[Skip to next coverage]
    I -->|Yes| J[Get eligibility transactions for visit and coverage]

    J --> K[Apply benefits to visit coverage using AutoBenefitsRule matching]
    K --> L[Apply benefits to quotes for this coverage using service-type-specific rules]
    L --> M{Update visit status if all quotes have benefits}

    M --> N
    N --> O{More coverages?}
    O -->|Yes| H
    O -->|No| P{More visits?}
    P -->|Yes| G
    P -->|No| Q[Save all visits in bulk]
    Q --> R[Save activity logs]
    R --> Z

    style J fill:#e1f5ff
    style K fill:#fff4e1
    style L fill:#fff4e1
    style Q fill:#e1f5ff

Processing Algorithm

The task uses a rule-based benefits selection algorithm:

Benefits Selection Process

1. Retrieve Visits: Load all visits from the batch table that have new eligibility transactions
2. Filter by API Access: Only process visits where the insurance has an ExternalAPI configured for benefits
3. For Each Visit Coverage:
   • Retrieve eligibility transactions for the visit and coverage combination
   • Apply to Visit Coverage: Match eligibility data to AutoBenefitsRule using insurance, service type (general code), plan/group info, and facility
   • Apply to Quotes: For each quote, match using the quote's specific service type code
4. Rule Matching: The BenefitsSelect component:
   • Finds all AutoBenefitsRule records matching insurance and service type
   • Filters by facility (if rule specifies facilities)
   • Filters by plan/group identifiers from eligibility transaction
   • Selects the most specific rule (prioritizes specific plans over AllPlansAndGroups)
   • Applies the rule's benefit amounts (Copay, Coinsurance, Deductible, MaxOutOfPocket)
5. Status Tracking: Sets AutoBenefitsStatus on coverage and quotes to indicate whether benefits were applied, ambiguous, or not found
6. Activity Logging: Records all benefit changes in ActivityLog table

Example Execution

For a visit with 2 quotes (service types "98" and "33") and 1 coverage (Aetna PPO):

Visit V-1, Insurance: Aetna PPO, Facility: FAC-001
  Eligibility Transactions: 2 responses from Availity API

Step 1: Apply to Visit Coverage (general service type)
  - Find AutoBenefitsRule: Insurance=Aetna, ServiceType=General, PlanID=PPO123
  - Rule result: Copay=$20, Deductible=$500
  - Apply to coverage.Benefits

Step 2: Apply to Quote 1 (ServiceType="98" - Physical Therapy)
  - Find AutoBenefitsRule: Insurance=Aetna, ServiceType=98, PlanID=PPO123
  - Rule result: Copay=$30, Deductible=$500
  - Apply to quote.Benefits

Step 3: Apply to Quote 2 (ServiceType="33" - Imaging)
  - Find AutoBenefitsRule: Insurance=Aetna, ServiceType=33, PlanID=PPO123
  - Rule result: Copay=$40, Coinsurance=20%, Deductible=$500
  - Apply to quote.Benefits

Step 4: Update Visit Status
  - All quotes have benefits applied
  - Set coverage.Benefits.AutoBenefitsStatus = BenefitsAutoApplied

Usage Examples

Example 1: Basic scheduled execution

// Run nightly after eligibility verification job completes
var task = new AutoApplyBenefitsTask();
// No parameters needed - automatically processes all batch visits with new eligibility transactions

Example 2: Part of a visit processing pipeline

// Step 1: Load visits from file or data source
var loadTask = new LoadDataFileTask { ... };

// Step 2: Run eligibility verification (separate process/API calls)
// ... eligibility verification creates EligibilityTxn records

// Step 3: Apply benefits from eligibility transactions
var autoBenefitsTask = new AutoApplyBenefitsTask();
// Automatically matches eligibility data to visits and applies benefit amounts

Example 3: After creating new AutoBenefitsRule configurations

// After configuring new rules in the UI, reprocess affected visits
var reprocessTask = new ReprocessChangedConfigurationsTask
{
    ReprocessVisits = true
};
// This queues visits that used the old rules

// Then run AutoBenefits to apply the new rules
var autoBenefitsTask = new AutoApplyBenefitsTask();

Related Tasks Comparison

Key Differentiators:

• AutoApplyBenefitsTask processes in batch mode for all visits with new eligibility data
• AutoBenefitsRealTime is for single-visit processing triggered by user actions in the UI
• Both use the same underlying AbstractAutoBenefits logic and AutoBenefitsRule matching
• Batch mode is more efficient for processing large numbers of visits (bulk save operations)

Performance Considerations

Database Impact

• Tables Read:
  • Visit (batch table): Filtered by visits with new eligibility transactions
  • Quote (batch table): All quotes joined to visits
  • EligibilityTxn: Retrieved for each visit/coverage pair
  • ExternalAPI: Checked for each unique insurance to filter visits
  • AutoBenefitsRule: Queried for each service type/insurance combination
• Tables Written:
  • Visit (batch table): Bulk update of all processed visits with benefits applied
  • ActivityLog: Batch insert of all benefit changes
• Query Patterns:
  • Single query to load all batch visits with new transactions
  • Single query to load all batch quotes
  • In-memory join of visits to quotes (no additional database query)
  • Per-coverage eligibility transaction lookup (indexed by VisitKey)
  • Per-service-type rule lookup (indexed by Insurance and ServiceType)
• Bulk Operations:
  • Visits saved in single bulk operation (SaveMany with bulk mode)
  • Activity logs saved in batch

Optimization Tips