Custom Salesforce forecasting operations runbook

A custom forecast is not finished when the grid reconciles on launch day. It is finished when an operator can explain why a number is wrong, identify which layer failed, and recover without guessing.

Use Building a Custom Forecasting Module in Salesforce for the calculation and UX architecture. This page is the operating runbook for what happens afterward.

Troubleshoot from the displayed number backward

When a manager says “this forecast is wrong,” do not start by reading component code. Start with the number they are looking at and walk backward through the contract.

1. 1
   Capture exact UI scope
2. 2
   Reproduce displayed number
3. 3
   Inspect contributing Opportunities
4. 4
   Validate record predicates
5. 5
   Validate owner + period membership
6. 6
   Validate source fields
7. 7
   Validate aggregation
8. 8
   Compare independent report

Capture the forecast model, selected owner/team, period range, measure lens, saved view, and any additional filters. “Q3 Commit is wrong” is not a reproducible defect until those dimensions are known.

Reconcile records before totals

A useful drill-through view is also your first diagnostic tool. If the displayed Commit figure is wrong, inspect the Opportunities that contribute to it.

There are only a few broad failure classes:

Symptom	Likely layer
Correct records, wrong total	Aggregation or currency/math logic
Missing Opportunity	Population, period, owner, or measure predicate
Extra Opportunity	Exclusion or predicate logic
Right Opportunity, wrong value	Source field or forecast-field calculation
Individual rows correct, manager rollup wrong	Hierarchy/membership aggregation
UI and export/report disagree	Scope, caching, or definition mismatch

This is why every displayed number should drill to records. Without that path, forecast troubleshooting becomes reverse engineering.

Hierarchy integrity is production data

Custom rollups often depend on a hierarchy or another explicit membership model. Treat that structure as forecast data, not merely org-chart decoration.

Check for users with forecast-relevant Opportunities who have no valid rollup path, inactive users who still own historical or open records, newly created roles that were not included in expected branches, and ownership changes whose effective period differs from the current hierarchy.

Do not silently drop a branch because its current user record looks inactive. Decide whether membership is current-state or period-aware and make the UI surface unresolved membership conditions.

Quota and target data can go stale independently

Forecast values and quotas have different writers and failure modes. A correct forecast divided by an old quota still produces a misleading operating view.

For native ForecastingQuota or another materialized target layer, monitor the last successful refresh/import, owner and period coverage, duplicate/missing facts, and the forecast-type/product context where applicable. Team totals should be explainable as the rollup of individual-period facts unless your contract explicitly says otherwise.

Never use “forecast refreshed successfully” as evidence that quota data is current.

History has a start boundary

If a Changes view reconstructs movement from tracked field events, it can only explain history that exists. Adding tracking today does not create yesterday's events.

Surface the effective tracking start date and distinguish “no change occurred” from “this period predates reliable change tracking.” If leadership needs exact historical states, capture immutable forecast snapshots rather than trying to infer a complete state from partial event history.

See History and snapshot design.

Cached AI narratives must match the UI scope

If the Changes view uses AI summaries, the narrative cache is another operating layer with its own failure modes. The structured change set remains authoritative.

Cache identity should include every dimension that changes the meaning of the narrative: forecast model, owner/team scope, forecast period, change window, exclusion state where relevant, and the model/prompt version when output compatibility matters.

A cache miss is safer than returning a narrative generated for the wrong scope. When operators report “the summary doesn't match the table,” compare the cache key with the exact UI state before debugging the model.

Pre-generated scopes and selectable UI scopes should also be reviewed together. Adding a new common window to the UI without adding it to pre-generation may create an unexpected latency regression even though the feature still works.

Saved preferences are not forecast data

Column widths, sort order, saved filters, and landing views can fail without changing a single forecast number. Keep that state separate from quotas, exclusions, snapshots, and calculation data.

If a preference record is missing or invalid, fall back to a safe default view. Do not let a personalization failure prevent the user from seeing the forecast itself.

Monitor the layers separately

A useful health surface distinguishes at least:

• Forecast calculation freshness.
• Hierarchy/membership exceptions.
• Quota/target freshness and coverage.
• Snapshot or change-history freshness.
• AI narrative generation/cache health.
• Saved-view/preference failures.
• Privileged write failures such as quota edits.

One green “forecast job succeeded” indicator cannot represent all of these systems honestly.

Recovery should preserve evidence

When an operator identifies bad data or a bad calculation release, prefer corrections that preserve what happened. Mark a change event as excluded rather than deleting it. Keep the failed job record. Version a corrected calculation contract. Preserve the prior snapshot if executives saw it.

The objective is not merely to make today's number right. It is to retain enough evidence to explain why yesterday's number was different.

Operator checklist

• Capture the exact owner, period, model, measure, and filter scope before troubleshooting.
• Reconcile the displayed figure to its contributing Opportunities.
• Check hierarchy/membership exceptions before assuming the aggregation code is wrong.
• Verify quota/target freshness independently from forecast freshness.
• Know the effective start date of reliable change history.
• Verify AI narrative cache identity against the current UI scope.
• Treat saved-view failures as preference failures, not forecast failures.
• Preserve failed jobs, exclusions, prior snapshots, and calculation versions during recovery.

Related: Building a Custom Forecasting Module in Salesforce, Forecast reporting governance, and How to Design a Forecasting System in Salesforce.