Deal health, forecasts, and quotas

The sales package calculates its metrics on demand. Nothing is cached or stored, and no scheduled job is involved: each method or action below runs its queries when you call it. The forecast, stage velocity, and quota calculations accept an optional $teamId that limits them to deals with that team_id; leave it null to include every team.

Rotting deals#

A stage's rot_after_days sets how long an open deal may sit in it. Two methods on Deal use it:

• daysInCurrentStage(): int: whole days since the deal entered its current stage (from the newest stage history row, or created_at if there is none).
• isRotten(): bool: true when the deal is open, its stage has a rot_after_days greater than zero, and daysInCurrentStage() is at least that number.

if ($deal->isRotten()) {
    $deal->logTask(
        title: "Unblock {$deal->name}",
        dueAt: now()->addDay(),
    );
}

There is no built-in command that flags or notifies on rotting deals. Rotting status feeds into the health score, the forecast's stale_deals_count, and stage velocity's stale_deal_count.

Health score#

$deal->getHealthScore() (backed by Odden\Sales\Actions\CalculateDealHealthScoreAction) returns a score from 0 to 100 with an explanation:

$health = $deal->getHealthScore();

$health['score'];           // int
$health['status'];          // 'strong', 'moderate', 'at_risk', or 'stalled'
$health['badge_color'];     // 'success', 'info', 'warning', or 'danger'
$health['badge_label'];     // Display label, for example "At Risk (42)" with a leading emoji
$health['factors'];         // list of ['name', 'points', 'positive', 'description']
$health['recommendations']; // list of strings

Won deals always score 100 (strong) and lost deals 0 (stalled). Open deals start at 50 and are adjusted:

The result for open deals is clamped to 5–99. Status is strong at 75 or more, moderate at 50 or more, at_risk at 30 or more, and stalled below that.

Any activity on the deal counts toward recency, including activities the package logs itself, such as stage automation tasks and quote portal views.

The sales package ships no view for this array, so it stays free of Filament. The Odden Filament package renders it on the deal page with odden-filament::deals.health-score-modal (passed as $health); outside Filament, build your own view from the array.

Pipeline forecast#

$pipeline->forecast() returns metrics for one pipeline; pass a team ID ($pipeline->forecast($teamId)) to count only that team's deals. Call Odden\Sales\Actions\CalculatePipelineForecastAction::execute(?int $pipelineId = null, ?int $teamId = null, ?Builder $visibleDeals = null, ?string $currency = null) directly with null to cover all pipelines.

use Odden\Sales\Actions\CalculatePipelineForecastAction;

$forecast = $pipeline->forecast();

$all = app(CalculatePipelineForecastAction::class)->execute();

All values are all-time; there is no date filter. Soft-deleted deals are excluded.

The figures cover one currency. Pass $currency to choose it; otherwise odden-sales.default_currency is used, or, when no deal uses that, the currency used by the most deals. Deals in other currencies are left out of the figures above and totalled per currency in other_currencies. There is no currency conversion.

Stage velocity#

Odden\Sales\Actions\CalculateStageVelocityAction::execute(?int $pipelineId = null, ?int $teamId = null) reports time spent per stage:

use Odden\Sales\Actions\CalculateStageVelocityAction;

$velocity = app(CalculateStageVelocityAction::class)->execute($pipeline->id);

$velocity['average_sales_cycle_days']; // float

foreach ($velocity['stages'] as $stageId => $metrics) {
    $metrics['stage_name'];
    $metrics['probability'];
    $metrics['average_dwell_days'];  // Average time in the stage for deals that have left it
    $metrics['transition_count'];    // How many times deals entered the stage
    $metrics['stale_deal_count'];    // Open deals in the stage past rot_after_days
}

average_sales_cycle_days is the average number of days from created_at to closed_at for won deals. stages is keyed by stage ID.

Quotas#

An Odden\Sales\Models\SalesQuota is a revenue target for one user:

Odden\Sales\Actions\CalculateQuotaAttainmentAction::execute(SalesQuota $quota, ?int $teamId = null) measures it (with a team ID, only that team's deals count toward the quota):

use Odden\Sales\Actions\CalculateQuotaAttainmentAction;
use Odden\Sales\Enums\QuotaPeriod;
use Odden\Sales\Models\SalesQuota;

$quota = SalesQuota::create([
    'user_id' => $rep->id,
    'pipeline_id' => $pipeline->id,
    'period_type' => QuotaPeriod::Quarterly,
    'period_start' => now()->startOfQuarter(),
    'period_end' => now()->endOfQuarter(),
    'target_amount' => 40000,
]);

$attainment = app(CalculateQuotaAttainmentAction::class)->execute($quota);

Deals count toward the user in owner_id. There is no currency conversion: deals in a different currency from the quota are not counted (see excluded_deal_count). Quotas are also used by quota-weighted lead routing.