Home / admin / collaborative-forecasts

collaborative-forecasts

Set up, configure or troubleshoot Salesforce Collaborative Forecasts: forecast types, forecast categories, rollup methods, quota management, forecast hierarchy, manager adjustments, pipeline inspection integration.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Operational Excellence
• Reliability

• collaborative-forecasts
• forecast-types
• forecast-categories
• quota-management
• forecast-adjustments
• cumulative-rollup
• opportunity-splits

Open the skill folder on GitHub

Collaborative Forecasts

This skill activates when a practitioner needs to design, configure, audit, or troubleshoot Salesforce Collaborative Forecasts. It covers forecast type configuration, forecast category mapping, rollup method selection, manager and owner adjustments, quota management, forecast hierarchy, and pipeline inspection integration.

Before Starting

Gather this context before working on anything in this domain:

• Collaborative Forecasts must be enabled in the org. Navigate to Setup > Forecasts Settings and confirm the feature is enabled; in metadata this is ForecastingSettings.enableForecasts (Metadata API Developer Guide, api_meta grep -n "^ *ForecastingSettings *$" 2nd hit, line 117436; field table from 117469; the data-loss warning at 117488). The guide warns "Disabling Forecasts can result in data loss." UNVERIFIED (2026-09-05): the edition list "Enterprise, Performance, Unlimited only" is not stated in the Metadata API guide or the Object Reference — and the Object Reference contradicts the exclusion of Professional, listing the API 57.0+ custom-date forecast types as available "in Performance, Professional, Enterprise, and Unlimited Edition with the Sales Cloud" (object_reference ForecastingType.DateType, from line 148700). Confirm the edition in the org, not from this list.
• The maximum number of forecast types is four. Grounded: "The maximum number of forecast types is four" on ForecastingSettings.forecastingTypeSettings (api_meta line 117503). Each type is independent with its own source, hierarchy and adjustable categories. UNVERIFIED (2026-09-05): the "raise the limit through a Salesforce Support case" route is not in either guide.
• Three grounded events purge forecast data — plan around all three. Setting active to false on a forecast type "purges all forecasting data, adjustments, and quotas for the forecast type" (api_meta line 117607); omitting a previously enabled type from the XML deactivates it and "its quota and adjustment data are deleted from the org" (api_meta line 117602); and setting enableAdjustments or enableOwnerAdjustments to false "results in adjustment data being purged" (api_meta lines 117837 and 117852). See references/gotchas.md Gotcha 9.
• Standard forecast categories: Pipeline, Best Case, Commit, Omitted, and Closed — "You can add a Most Likely category and can customize forecast category names in single category rollups" (object_reference ForecastingOwnerAdjustment.ForecastCategoryName, line 147671). Omitted opportunities are excluded from all forecast rollups. UNVERIFIED (2026-09-05): "Manager Judgment is unavailable for split-based forecast types" is not stated in either guide; ForecastingType.HasAdjustments (object_reference line 148759) carries no split carve-out. Verify in the target org before telling managers.

Questions to Ask Before Configuring

Ask these before creating a single forecast type. Every row here exists because a documented behaviour punishes the wrong answer later, and several of the answers cannot be changed afterwards without purging data.

What a proper configuration adds over just doing it: the four category API names, the measure field, the hierarchy type and the quota grain are all decided and deployable before the first type goes active, so the org never has to reach the settings that purge forecasting data, adjustments and quotas to fix a wrong guess.

Core Concepts

Forecast Types

A Forecast Type defines what a forecast measures and how it is organized. Each Forecast Type has three independent configuration dimensions:

1. Source object — what data the forecast rolls up:

1. Forecast hierarchy — the organizational dimension:

1. Measurement field — the currency field used for rollup (Amount, Expected Revenue, or a custom field).

Up to 4 active Forecast Types are permitted by default. Each type appears as a separate tab on the Forecasts page.

Forecast Categories

Five standard forecast categories map opportunity stages to forecast buckets. The mapping is configured per org and applies globally to all Forecast Types.

Each opportunity stage must map to exactly one forecast category. Stages mapped to Omitted do not appear in any forecast view. There is no limit on how many stages map to each category.

Manager Judgment: An additional adjustment layer that managers can apply on top of subordinate-submitted forecasts. Not available for split-based forecast types (Opportunity Splits, Product Splits).

Rollup Methods

The rollup method controls which forecast category values are shown in each column on the forecast page:

There is no rollupType element. The rollup method is expressed by which set of four values you put in forecastedCategoryApiNames — "Changing from one set of four values to the other changes the organization setting for Enable Cumulative Forecast Rollups in Setup. If this field is omitted, the setting isn't changed" (api_meta line 117655).

Note what the guide adds that the usual summary drops: cumulative Best Case includes Most Likely as well as Commit and Closed, and cumulative OpenPipeline does not include Closed. MostLikelyOnly / MostLikelyForecast exist as a fifth category only where Most Likely has been added.

Cumulative rollup gives managers expected revenue (committed pipeline plus won deals). Single-category rollup is useful when reps need distinct stage breakdowns; forecast category names can be customised only in single-category rollups (object_reference line 147671).

Critical constraint: treat the rollup method as a one-way decision before go-live. The rollup switch's effect on existing adjustments is UNVERIFIED (2026-09-05) — neither guide documents it — but the three purge events listed under Before Starting are documented, so export ForecastingAdjustment and ForecastingOwnerAdjustment before touching forecast-type settings regardless.

Quotas

Quotas are per-user, per-period revenue targets loaded against a specific Forecast Type. Quotas enable the "% of Quota" attainment column on the forecast page.

Quotas are enabled by globalQuotasSettings/showQuotas (api_meta line 117513; QuotasSettings subtype at 117948, showQuotas at 117958) and loaded via Data Loader / API against ForecastingQuota, or the Manage Quotas import in Setup.

ForecastingQuota field behaviour, from object_reference (grep -n "^ *ForecastingQuota *$" 5th hit, line 147887):

Retrieve the type ids first — ForecastingType.DeveloperName "is called name in the Metadata API and Forecasting Type in custom reports" (object_reference line 148741), so the metadata name and the queryable DeveloperName are the same string.

Forecast Adjustments

Two types of adjustments exist on the forecast:

The two adjustment layers are two different objects, and the naming in the UI is easy to invert:

Both toggles are org-wide from API 53.0 on ("All forecast types must contain the same enableAdjustments value"), and both carry the same warning: "Disabling adjustments results in adjustment data being purged."

Which columns are adjustable is set by managerAdjustableCategoryApiNames and ownerAdjustableCategoryApiNames — each read-only, each appearing exactly twice, each restricted to bestcaseforecast/commitforecast (cumulative) or bestcaseonly/commitonly (individual), and "if both … fields are being used, they must contain the same two values" (api_meta lines 117703 and 117799). ForecastingAdjustment.AdjustmentNote is capped at 255 characters and "doesn't appear in reports" (object_reference line 145600).

Mode 1 — Configure Collaborative Forecasting From Scratch

Use this mode when enabling and setting up Collaborative Forecasts for the first time or adding a new Forecast Type.

Step 1 — Enable Collaborative Forecasts. Navigate to Setup > Forecasts Settings. Enable Collaborative Forecasts for the org. Select the default forecast currency (single currency org) or confirm multi-currency settings if applicable.

Step 2 — Configure Forecast Categories. In Setup > Forecasts Settings, review the stage-to-category mapping. Map every opportunity stage to a forecast category. Confirm which stages are Omitted (Closed Lost, disqualified stages, etc.). Omitted opportunities are excluded from all rollups.

Step 3 — Create Forecast Types. For each distinct sales motion (e.g., AE Revenue by Role, SE Overlay Splits, Product Family Revenue), create a Forecast Type with:

• Source object (Opportunity, Opportunity Product, Opportunity Splits, etc.)
• Measurement field (Amount, Expected Revenue, or custom currency field)
• Hierarchy type (role vs territory)
• Period type (monthly vs quarterly)
• Rollup method (cumulative vs single-category) — decide before enabling; cannot be changed without losing adjustments

Step 4 — Activate the type. In metadata this is the second deploy, not a separate screen: a type created through ForecastingType lands inactive and the same package must be deployed again to set active. Then confirm the four displayedCategoryApiNames values match the four forecastedCategoryApiNames values — "Always use the same 4 values for both" (api_meta line 117617).

Step 5 — Enable Forecast Users and Assign Forecast Managers. Go to each user's detail page (or bulk-configure via API) and set ForecastEnabled = true — labelled Allow Forecasting under General Information. Without this flag, a user is invisible in the forecast rollup even if they have the correct role; role assignment alone never sets it. The same enablement is also reachable from Setup > Forecasts Hierarchy > Enable Users, moving users between Available Users and Enabled Users — a second path to the same flag, not a substitute for it. Then, on the same Forecasts Hierarchy page, click Assign Manager / Edit Manager on every role that should roll up: if no forecast manager is assigned to a role, neither that role nor its subordinate roles are included in forecasts. Forecast users also need View Roles and Role Hierarchy to access role-based forecasts in Lightning Experience — assigned to all forecast users by default, so only verify it when a user cannot open the tab.

Step 6 — Load Quotas (if needed). Use Data Loader or the quota import wizard to upload ForecastingQuota records for each user, period, and forecast type. Verify attainment column appears on the forecast page after load.

Step 7 — Validate. Navigate to the Forecasts tab as a manager role. Confirm subordinate users appear in the hierarchy. Confirm stage mapping produces expected rollup totals. Check that cumulative/single-category behavior matches expectation.

Mode 2 — Audit an Existing Forecast Configuration

Use this mode when reviewing an existing setup for correctness, investigating missing data, or preparing for a change.

Check active Forecast Type count. Navigate to Setup > Forecasts Settings. Confirm the number of active types is 4 or fewer (default limit). Flag if the org is approaching the limit.

Review stage-to-category mapping. Confirm all active opportunity stages are mapped. Flag any stages mapped to Omitted that should be in the pipeline. Unintentionally-Omitted stages will silently exclude revenue from all forecasts.

Check rollup method per Forecast Type. Document the rollup method (cumulative vs single-category) for each type before making any changes. Verify method matches stakeholder reporting expectations.

Audit forecast user enablement. Query SELECT Id, Name FROM User WHERE ForecastEnabled = true AND IsActive = true. Compare against expected forecast users.

Check quota coverage. Query ForecastingQuota for coverage across expected users and periods. Flag missing quotas for active forecast users.

Mode 3 — Troubleshoot Forecast Data Issues

Use this mode when forecast rollups show unexpected amounts, users are missing from the hierarchy, or adjustments behave unexpectedly.

Users missing from forecast hierarchy:

• Confirm ForecastEnabled = true (Allow Forecasting) on the user record.
• Confirm the user has a role assigned and the role is in the forecast hierarchy. For a role-based Forecast Type, a user with no role has no node in the hierarchy and cannot forecast at all.
• Confirm the role — and every role above it — has a forecast manager assigned. If no forecast manager is assigned to a role, neither that role nor its subordinate roles are included in forecasts.
• For territory-based forecast types: confirm the user is a territory member in the active territory model. Territory-based types roll up through the territory hierarchy, so a role-less user can still appear there.

Forecasts tab blank or inaccessible in Lightning Experience:

• Check the View Roles and Role Hierarchy permission — it is required to access role-based forecasts in Lightning Experience. It is assigned to all forecast users by default and is automatically enabled by View Setup and Configuration, View All Forecasts, Override Forecasts, or Delegated External Portal User, so admins rarely reproduce the failure.
• Confirm the Forecasts tab itself is in the app's navigation items or set to Default On.

Opportunities not appearing in forecast:

• Check the opportunity stage — stages mapped to Omitted are excluded by design.
• For split-based types: confirm splits are populated on the opportunity.
• For product-based types: confirm opportunity line items exist with expected product families.
• For schedule-based types: confirm revenue schedules exist with dates in the current forecast period.

Adjustment missing after rollup method change:

• Adjustments are permanently deleted when the rollup method is switched. There is no recovery. Rebuild adjustments if needed.

Quota attainment not showing:

• Confirm ForecastingQuota records exist for the user, period, and specific ForecastingTypeId.
• Confirm the quota period start date matches the forecast period boundary exactly.

Decision Guidance

Recommended Workflow

1. Answer the seven questions above and retrieve what already exists. sf project retrieve start --metadata "Settings:Forecasting" ForecastingType ForecastingSourceDefinition ForecastingTypeSource "StandardValueSet:OpportunityStage" --target-org <sandbox>. The settings land in settings/Forecasting.settings-meta.xml — not ForecastingSettings.settings. Fill in templates/collaborative-forecasts-template.md as you go.
2. Write the org-wide block first. enableForecasts, all eight forecastingCategoryMappings, globalAdjustmentsSettings, globalForecastRangeSettings, globalQuotasSettings — copy the shapes from references/metadata-examples.md § "Two forecast types in one Forecasting.settings". Orgs using either rollup style "must include all eight occurrences of this subtype".
3. Deploy the stage→category mapping in the same change as the stages. StandardValueSet: OpportunityStage, one forecastCategory per standardValue, using the metadata enum (Omitted, Pipeline, BestCase, Forecast, Closed) — Forecast is the value the UI labels Commit. See references/gotchas.md Gotcha 10.
4. Author the forecast types, then run the checker. For legacy types, a forecastingTypeSettings block with the exact name from the guide's enum; for anything new, a .forecastingType plus .forecastingSourceDefinition plus .forecastingTypeSource triple. Then: python3 skills/admin/collaborative-forecasts/scripts/check_collaborative_forecasts.py --manifest-dir force-app/main/default, which enforces the category-enum, date-type, amount/quantity and quota-CSV rules the platform will otherwise fail on silently.
5. Deploy twice. sf project deploy validate then sf project deploy start, then run the same deploy again: a new forecast type "is created in the inactive state" on the first pass and only the second pass flips active. Order is ForecastingSettings → ForecastingType → ForecastingSourceDefinition → ForecastingTypeSource, applied automatically when all four are in one package.
6. Enable the people, not just the metadata. Set User.ForecastEnabled = true for every forecast user and UserRole.ForecastUserId for every role that must roll up; both are updateable via API, so this is a Data Loader step, not a click-through. Verify with the two SOQL queries in references/metadata-examples.md § Verification.
7. Load quotas, then verify the numbers, not the record count. Load ForecastingQuota with QuotaOwnerId, ForecastingTypeId, StartDate, and exactly one of QuotaAmount / QuotaQuantity; omit PeriodId and IsAmount/IsQuantity. Then query ForecastingItem as a manager and reconcile against a pipeline report before handing the tab to sales.

Review Checklist

Run through these before marking Collaborative Forecasts setup complete:

• [ ] Collaborative Forecasts is enabled in Setup > Forecasts Settings
• [ ] All active opportunity stages are mapped to a forecast category (no unmapped stages)
• [ ] Omitted stage mapping is intentional — no revenue-generating stages mapped to Omitted
• [ ] Rollup method (cumulative vs single-category) is documented and matches stakeholder requirements
• [ ] All active Forecast Types are within the four-type maximum
• [ ] All expected forecast users have ForecastEnabled = true on their user record
• [ ] Each forecast user has the correct role in the role hierarchy (or territory membership for territory types)
• [ ] Every role that should roll up has a forecast manager assigned — an unassigned role node drops that role and all its subordinate roles from forecasts
• [ ] Quotas are loaded for the current period if attainment display is required, with PeriodId, IsAmount and IsQuantity absent from the load file
• [ ] The package was deployed twice, and SELECT DeveloperName, IsActive, LastActivatedDate FROM ForecastingType confirms every new type is actually active
• [ ] Forecasting.settings was retrieved from the target org before editing — the deployed file has no fewer forecastingTypeSettings blocks than the retrieved one
• [ ] Every opportunity stage in StandardValueSet: OpportunityStage carries a forecastCategory, using the metadata enum (Forecast, not Commit)
• [ ] Consumers of ForecastCategoryName were inventoried before any switch to cumulative rollups
• [ ] python3 skills/admin/collaborative-forecasts/scripts/check_collaborative_forecasts.py --manifest-dir <dir> exits 0
• [ ] Split-based types have Opportunity Splits enabled and splits populated on opportunities
• [ ] Forecast adjustments are intentionally configured (enabled/disabled) per stakeholder preference
• [ ] Manager adjustment availability communicated to managers (not available for split-based types)

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Switching rollup method deletes all adjustments permanently — When you change a Forecast Type from single-category to cumulative rollup (or vice versa), Salesforce deletes all existing manager adjustments and owner adjustments for that type with no warning and no recovery path. Always capture adjustment values via Data Loader before making the change if they need to be preserved.
2. ForecastEnabled must be set per user — role alone is not enough — A user with the correct role in the role hierarchy will be completely invisible in the forecast rollup unless their ForecastEnabled field is set to true. New users are not automatically enabled. Include ForecastEnabled = true in every user provisioning workflow.
3. Manager Judgment is not available for split-based Forecast Types — For Forecast Types sourced from Opportunity Splits or Product Splits, Manager Judgment is silently unavailable. Managers cannot adjust subordinate forecast totals on these types. Communicate this to sales managers before rollout.
4. Omitted stages are silently excluded from every rollup — Any opportunity stage mapped to Omitted is excluded from all forecast rollup totals, including Pipeline. A revenue-generating stage mistakenly mapped to Omitted causes revenue to disappear from forecasts with no error message. Audit stage mapping carefully and re-audit whenever stage picklists change.
5. A quota load fails on the columns you added, not the date you feared — ForecastingQuota.StartDate accepts any day in the target month and is stored as the first of the month, so a date shift is not the usual cause of blank attainment. The real load-breakers are read-only and derived fields: PeriodId is read-only, and IsAmount/IsQuantity have no Create property. See references/gotchas.md Gotcha 5.
6. A new forecast type deploys inactive — the first deploy never turns it on — Types available only in API 52.0 and later are created in the inactive state; the guide's instruction is to deploy the zip file twice. Legacy pre-Summer '21 types are the inverse: they can be deactivated but not activated, created, or deleted through ForecastingType. See references/gotchas.md Gotcha 11.
7. ForecastCategoryName goes null under cumulative rollups — Cumulative forecast amounts span multiple forecast categories, so the field that identifies a single category has nothing to hold. Reports and integrations that group on it break at the moment the org switches. See references/gotchas.md Gotcha 12.
8. The metadata enum for the Commit category is spelled Forecast — On StandardValueSet: OpportunityStage, the deployable forecastCategory values are Omitted, Pipeline, BestCase, Forecast, Closed. Deploying Commit fails; deploying nothing leaves the stage unmapped. See references/gotchas.md Gotcha 10.

Output Artifacts

Reference Files

Related Skills

• admin/enterprise-territory-management — use when the org needs territory-based forecast types; roleType Y requires an active Territory2Model, and Territory2.ForecastUserId names the territory forecast manager
• admin/opportunity-management — owns opportunity stage design, forecast category vocabulary, splits configuration, and the product/schedule setup that feeds forecast source definitions
• admin/sales-process-mapping — owns which stages exist per sales process before you map any of them to a forecast category
• admin/pipeline-review-design — owns the review cadence and the reports the forecast tab is reconciled against; read it before deciding what the Commit column must mean to the business
• admin/user-management — owns User.ForecastEnabled and role assignment in provisioning; the forecast hierarchy is generated from the role hierarchy, so role design is decided there
• admin/sharing-and-visibility — use for role hierarchy design; role structure directly determines which users appear in a role-based forecast hierarchy

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/collaborative-forecasts-template.md
• scripts/check_collaborative_forecasts.py