Skip to main content

Rating System Overview

The rating system transforms raw usage events (EDRs) into priced wallet operations.

Complete Rating Flow​

EDR (OPEN)
  ↓ UsageRatingService.rateUsage()
  ↓ Match UsageChargeInstance by filterParam1-4 + filterExpression
  ↓
UsageChargeInstance (matched)
  ↓ PricePlanSelectionService.determineDefaultPricePlan()
  ↓
PricePlanMatrix Selection (Step 1 - Container)
  Filters: chargeCode, seller, offer, country, currency, criteria1-3,
           subscriptionDateRange, ratingDateRange, subscriptionAge, quantity
  Ordered by: priority ASC
  ↓
PricePlanMatrixVersion Selection (Step 2 - Active Version)
  Filters: status=PUBLISHED, validity.from <= operationDate < validity.to
  ↓
PricePlanMatrixLine Selection (Step 3 - Price Line)
  If isMatrix=false: use version.price directly
  If isMatrix=true:
    - Match attribute values against line values
    - Order by priority ASC, ratingAccuracy DESC
    - Return first fully matching line
    - Fallback: line with ratingAccuracy=0 (default)
  ↓
WalletOperation Created
  - Stores: priceplan, pricePlanMatrixVersion, pricePlanMatrixLine
  - Status: OPEN
  ↓
RatedTransaction Created (aggregation)
  - Status: OPEN → BILLED (at invoicing)

Key Entities​

EDR (Event Detail Record)​

Raw usage event before rating.

Key Fields:

  • subscription - Target subscription
  • quantity - Usage amount
  • parameter1-9 - String parameters
  • dateParam1-5 - Date parameters
  • decimalParam1-5 - Numeric parameters
  • status - OPEN → RATED or REJECTED

WalletOperation​

Priced result of rating.

Key Fields:

  • amountWithoutTax, amountWithTax - Calculated amounts
  • unitAmountWithoutTax, unitAmountWithTax - Per-unit amounts
  • rawAmountWithoutTax, rawAmountWithTax - Before minimum
  • priceplan, pricePlanMatrixVersion, pricePlanMatrixLine - Pricing context
  • status - OPEN → TREATED (when RT created) → RERATED
  • overrodePrice - Manual override flag

RatedTransaction​

Aggregated transaction for invoicing.

Key Fields:

  • walletOperations - Source wallet operations
  • invoiceLine - Target invoice line
  • status - OPEN → BILLED (invoiced) → CANCELED

EDR Status Lifecycle​

OPEN → RATED (success)
     → REJECTED (failure)
     → CANCELLED (versioning conflict)
     → DUPLICATED
     → AGGREGATED
     → MEDIATING

WalletOperation Status​

OPEN → TREATED (RT created)
     → RERATED (if re-rated)
     → CANCELED (if reversed)

Price Override Mechanisms​

1. ChargeInstance Level​

ChargeInstance ci = ...;
ci.setAmountWithoutTax(new BigDecimal("100.00"));
ci.setAmountWithTax(new BigDecimal("120.00"));
ci.setApplyDiscountsOnOverridenPrice(true);

2. WalletOperation Level​

WalletOperation wo = ...;
wo.setOverrodePrice(true);
wo.setUnitAmountWithoutTax(new BigDecimal("50.00"));

3. PricePlanMatrix EL Expressions​

PricePlanMatrix ppm = ...;
ppm.setAmountWithoutTaxEL("#{basePrice * (1 - discount)}");
ppm.setAmountWithTaxEL("#{amountWithoutTax * 1.2}");

4. Script-Based Pricing​

PricePlanMatrix ppm = ...;
ppm.setScriptInstance(customPricingScript);

5. Discount Plans​

Negative wallet operations created via DiscountPlan.

Counter Management​

Counters track usage limits and aggregation.

CounterTemplate​

  • counterType - CONSUMPTION (decrement) or ACCUMULATOR (sum)
  • ceiling - Maximum value for consumption counters
  • calendar - Period reset timing
  • notificationLevels - JSON for threshold alerts

CounterPeriod​

  • periodStartDate, periodEndDate - Period boundaries
  • value - Current accumulated value
  • level - Current notification level

Counter-Based Rating​

EDR arrives
  ↓
Check CounterPeriod.value
  ↓
If ceiling reached → Rate at overage price
If not reached → Decrement counter (no charge)
  ↓
At billing period end → Aggregate and apply tiered pricing