ForecastingSettings

This information only applies to Collaborative Forecasts.

Note

In the package manifest, all organization settings metadata types are accessed using the Settings name. See Settings for more details.

File Suffix and Directory Location

ForecastingSettings values are stored in a single file named Forecasting.settings in the settings directory of the corresponding package directory. The .settings files are different from other named components because there’s only one settings file for each settings component.

Version

ForecastingSettings components are available in API version 28 and later. The structure of the ForecastingSettings type changed significantly in API version 30.0.

Fields

Field Name	Field Type	Description
displayCurrency	DisplayCurrency (enumeration of type string)	Removed. The currency for displaying forecasts; either the organization's corporate currency or each forecast owner's personal currency setting. The selected currency is the default used in Collaborative Forecasts and selected in setup. The selection must be one of the currencies enabled for use in the organization, and only one selection is allowed. The default is `CORPORATE`. The valid values are: `CORPORATE` `PERSONAL` Available in API version 28.0 to 46.0. In API version 47.0 and later, use defaultToPersonalCurrency.
defaultToPersonalCurrency	boolean	If multicurrency is enabled, this field indicates whether the user’s personal currency is used in forecasts. If `true` (default), the user’s personal currency is used. If `false`, the corporate currency is used. Available in API version 47.0 and later.
enableForecasts	boolean	Indicates if Collaborative Forecasts is enabled or not. Set to `true` to enable Collaborative Forecasts and `false` to disable the functionality. Disabling Forecasts can result in data loss. Refer to Salesforce Help before disabling any functionality. Warning
forecastingCategoryMappings	ForecastingCategoryMapping[]	A list of mappings associating forecast types with forecast rollups. As of Spring ’20 and later, only standard users with the View All Forecasts or Allow Forecasting permission or delegated forecast manager status can access this subtype.
forecastingDisplayedFamilySettings	ForecastingDisplayedFamilySettings[]	The product families chosen to allow forecasting on in Lightning Experience. This field is available in API version 40.0 and later.
forecastingTypeSettings	ForecastingTypeSettings[]	A list of forecast types. For field values, see ForecastingTypeSettings. The maximum number of forecast types is four.

ForecastingCategoryMapping

The forecasting category mappings for Collaborative Forecasts. This subtype appears eight times within the ForecastingSettings type. Each occurrence includes fields that specify a type of forecast category rollup, which forecast categories each rollup includes, and the weight of each forecast category in the rollup. Organizations using either cumulative forecast rollups or individual forecast category columns must include all eight occurrences of this subtype. As of Spring ’20 and later, only standard users with the View All Forecasts or Allow Forecasting permission or delegated forecast manager status can access this subtype.

Field	Field Type	Description
forecastingItemCategoryApiName	string	Required. This field specifies the API name of the rollup type. The valid values are: `openpipeline` `bestcaseforecast` `commitforecast` `pipelineonly` `bestcaseonly` `commitonly` `closedonly` `omittedonly`
weightedSourceCategories	WeightedSourceCategory[]	This field can occur more than once when specifying more than one forecast category to include in the rollup type. Each occurrence contains two subfields that specify a forecast category to include in the forecast rollup type and its weight. Some rollup types include more than one forecast category. This list shows the forecast categories that are included in each rollup type. Rollup: `openpipeline`, Forecast categories: pipeline, best case, commit Rollup: `bestcaseforecast`, Forecast categories: best case, commit, closed Rollup: `commitforecast`, Forecast categories: commit, closed Rollup: `pipelineonly`, Forecast categories: `pipeline` Rollup: `bestcaseonly`, Forecast categories: `best case` Rollup: `commitonly`, Forecast categories: `commit` Rollup: `closedonly`, Forecast categories: `closed` Rollup: `omittedonly`, Forecast categories: `omitted`

ForecastingDisplayedFamilySettings

The product families that an admin chooses to allow forecasting on in Lightning Experience. This field is available in API version 40.0 and later.

Field	Field Type	Description
productFamily	string	The product family available to forecast on. Each product family is unique.

ForecastingTypeSettings

The settings for each forecast type. An organization can have up to four forecast types active. If you omit a previously enabled forecast type that has a minimum API version less than or equal to the metadata package version, its quota and adjustment data is deleted from the org.

Omitting a forecast type field from the XML can deactivate that forecast type: if the forecast type was available in the release specified by the XML package version, that forecast type is deactivated and its quota and adjustment data are deleted.

Warning

Field Name	Field Type	Description
active	boolean	Required. Indicates whether the forecast type specified in the name field is active. Setting the active field to false purges all forecasting data, adjustments, and quotas for the forecast type. When active is set to true, some values on the Forecasts tab might not appear immediately. An in-process icon appears to indicate that the values are being calculated. Note
adjustmentsSettings	AdjustmentsSettings	Required. This enables or disables the Forecasts adjustments option in Forecasts.
displayedCategoryApiNames	string	This read-only field appears four times to specify the four forecast rollup categories displayed in the Forecasts tab, for either cumulative forecast rollups, or individual forecast category rollups. Always use the same 4 values for both displayedCategoryApiNames and forecastedCategoryApiNames. Valid values for organizations using cumulative forecast rollups: `openpipeline` `bestcaseforecast` `commitforecast` `closedonly` Valid values for organizations using individual forecast category rollups: `pipelineonly` `bestcaseonly` `commitonly` `closedonly`
forecastedCategoryApiNames	string	This field appears four times to specify the four forecast rollup categories used in the organization, for either cumulative forecast rollups, or individual forecast category rollups. Valid values for organizations using cumulative forecast rollups: `openpipeline` `bestcaseforecast` `commitforecast` `closedonly` Valid values for organizations using individual forecast category rollups: `pipelineonly` `bestcaseonly` `commitonly` `closedonly` 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 is not changed.
ForecastingDateType	ForecastingDateType (enumeration of type string)	Required. The date type that forecast amounts are based on in Collaborative Forecasts. Valid values are: `OpportunityCloseDate` (default) `ProductDate` `ScheduleDate` Available in API version 42.0 and later. In API version 42.0 only, date types are read only and available only via API.
forecastRangeSettings	ForecastRangeSettings	Required. The default periods and range selections in Collaborative Forecasts.
hasProductFamily	boolean	Required. Indicates whether the forecasting type has product family forecasts enabled. Available in API version 41.0 and later.
isAmount	boolean	Required. This read-only field indicates whether the forecast type is based on revenue amounts. The value of isAmount is always the opposite of the value of isQuantity.
isAvailable	boolean	Required. This read-only field indicates whether the forecast type can currently be used in the organization. For example, the revenue splits forecast type can’t be used in an organization that doesn’t have Opportunity Splits enabled.
isQuantity	boolean	Required. This read-only field indicates whether the forecast type is based on product quantities. The value of isQuantity is always the opposite of the value of isAmount.
managerAdjustableCategoryApiNames	string	This read-only field appears twice to specify the two forecast rollup categories that forecast managers can adjust in the organization for either cumulative forecast rollups or individual forecast category rollups. This field can only be used when the enableAdjustments field contains a value of true. If both the managerAdjustableCategoryApiNames and ownerAdjustableCategoryApiNames fields are being used, they must contain the same two values. Their values must also be consistent with the values of the enableAdjustments and enableOwnerAdjustments fields. Valid values for organizations using cumulative forecast rollups: `bestcaseforecast` `commitforecast` Valid values for organizations using individual forecast category rollups: `bestcaseonly` `commitonly`
masterLabel	string	Required. This read-only field indicates the UI label for the forecast type.
name	string	Required. The name of the forecast type. Each forecast type requires a specific string. Valid values include: `LineItemQuantityProductDate` : Product Families - Quantity by product date. Available in API version 47.0 and later. `LineItemQuantityScheduleDate` : Product Families - Quantity by schedule date. Available in API version 47.0 and later. `LineItemRevenueProductDate` : Product Families - Revenue by product date. Available in API version 47.0 and later. `LineItemRevenueScheduleDate` : Product Families - Revenue by schedule date. Available in API version 47.0 and later. `OpportunityLineItemQuantity` : Product Families - Quantity `OpportunityLineItemRevenue` : Product Families - Revenue `OpportunityOverlayRevenue` : Opportunity Overlay Splits - Revenue `OpportunityQuantity` : Opportunities - Quantity `OpportunityQuantityProductDate` : Opportunities - Quantity by product date. Available in API version 43.0 and later. `OpportunityQuantityScheduleDate` : Opportunities - Quantity by schedule date. Available in API version 43.0 and later. `OpportunityRevenue` : Opportunities - Revenue `OpportunityRevenueProductDate` : Opportunities - Revenue by product date. Available in API version 43.0 and later. `OpportunityRevenueScheduleDate` : Opportunities - Revenue by schedule date. Available in API version 43.0 and later. `OpportunitySplitRevenue` : Opportunity Revenue Splits - Revenue `Territory_Model_NameN`: Territories, where `Territory_Model_Name` is the name of your active territory model in the API. `Territory_Model_Name` can be followed by `N`, an auto-generated number that distinguishes between territory forecast types. Available in API version 44.0 and later. `Territory_Model_NameN_ProductFamily`: Deprecated. Territories - Product Families, where `Territory_Model_Name` is the name of your active territory model in the API and can be followed by `N`, an auto-generated number that distinguishes between territory forecast types. Available in API version 45.0 and 46.0. For territory models created in API version 47.0 and later, `Territory_Model_NameN` is used. The name of a custom opportunity split type that has been enabled as a forecast type. Custom split types are based on currency fields, which can contain revenue amounts only.
opportunityListFieldsLabelMappings	OpportunityListFieldsLabelMapping	A read-only list of the API names and UI labels for all fields on the Opportunity object.
opportunityListFieldsSelectedSettings	OpportunityListFieldsSelectedSettings	Required. The fields selected to appear in the opportunity pane of the forecast page for the forecast type. One of the selected fields must be Opportunity Name. You can select up to 15 fields.
opportunityListFieldsUnselectedSettings	OpportunityListFieldsUnselectedSettings	Required. The fields not selected to appear in the opportunity pane of the forecast page for the forecast type.
opportunitySplitName	string	Indicates whether the forecasting type has a split type, and if so, the name of the split type. Available in API version 41.0 and later.
ownerAdjustableCategoryApiNames	string	This read-only field appears twice to specify the two forecast rollup categories that forecast owners can adjust in the organization, for either cumulative forecast rollups, or individual forecast category rollups. This field can only be used when the enableOwnerAdjustments field contains a value of true. If both the managerAdjustableCategoryApiNames and ownerAdjustableCategoryApiNames fields are being used, they must contain the same two values. Their values must also be consistent with the values of the enableAdjustments and enableOwnerAdjustments fields. Valid values for organizations using cumulative forecast rollups: `bestcaseforecast` `commitforecast` Valid values for organizations using individual forecast category rollups: `bestcaseonly` `commitonly`
quotasSettings	QuotasSettings	Required. This enables or disables the quota option in Forecasts.
territory2ModelName	string	Indicates whether the forecasting type has a Territory2 model, and if so, the name of the Territory2 model. Available in API version 41.0 and later.

AdjustmentsSettings

The adjustment options for Collaborative Forecasts.

Field	Field Type	Description
enableAdjustments	boolean	Required. Set to `true` to enable Collaborative Forecasts manager adjustments and `false` to disable them. All forecast types must contain the same enableAdjustments value. Disabling adjustments results in Collaborative Forecasts adjustment data being purged. Warning
enableOwnerAdjustments	boolean	Required. Set to `true` to enable Collaborative Forecasts owner adjustments and `false` to disable them. All forecast types must contain the same enableAdjustments value. Disabling adjustments results in Collaborative Forecasts adjustment data being purged. Warning

ForecastRangeSettings

The default periods and range selections in Collaborative Forecasts. Users can forecast up to 15 months, 15 fiscal periods, or 8 quarters in the future or past. If your forecast range includes the current month, period, or quarter, the forecasts page displays the current month, period, or quarter by default. If not, the first month, period, or quarter of the range is selected. All forecast types must contain the same forecastRangeSettings field values.

If you change the time period from monthly to quarterly or quarterly to monthly, or you change the standard fiscal year, all adjustments and quotas are purged. If you enable custom fiscal years, creating the first custom fiscal year deletes any quotas and adjustments in the corresponding and subsequent standard fiscal years. These changes trigger a forecast recalculation that can take significant time, depending on the quantity of your data.

Warning

Field	Field Type	Description
beginning	int	Required. Indicates the beginning month or quarter to display by default.
displaying	int	Required. Indicates the number of months or quarters to display by default. The maximum number of months is 12 and quarters is 8.
periodType	PeriodTypes (enumeration of type string)	Required. Indicates what type of period to use. Valid values are: `Month` `Quarter` `Week` `Year`

OpportunityListFieldsLabelMapping

A read-only list of the API names and UI labels for all fields on the Opportunity object.

Field	Field Type	Description
field	string	Required. The API name of the Opportunity field.
label	string	Required. The UI label of the Opportunity field.

OpportunityListFieldsSelectedSettings

The fields selected to appear in the opportunity pane of the forecast page for the forecast type. One of the selected fields must be Opportunity Name. You can select up to 15 fields.

Field	Field Type	Description
field	string	Specifies names of fields to display in the opportunity pane.

OpportunityListFieldsUnselectedSettings

The fields not selected to appear in the opportunity pane of the forecast page for the forecast type.

Field	Field Type	Description
field	string	Specifies names of fields not displayed in the opportunity pane.

QuotasSettings

QuotasSettings indicates if quotas are available in Collaborative Forecasts.

Field	Field Type	Description
showQuotas	boolean	Required. Set to `true` to enable quotas. All forecast types must contain the same showQuotas field value.

WeightedSourceCategory

This field can occur more than once when specifying more than one forecast category to include in the rollup type. Each occurrence contains two subfields that specify a forecast category to include in the forecast rollup type and its weight. Some rollup types include more than one forecast category. This table shows the forecast categories that are included in each rollup type.

Field	Field Type	Description
sourceCategoryApiName	string	Required. Specifies the API name of a forecast category to include in the rollup type. The valid values are. `pipeline` `best case` `commit` `closed` `omitted`
weight	double	Required. Specifies the weight given to the forecast category when calculating the forecast for the rollup type. The only supported value is `1.0`.

Declarative Metadata Sample Definition

The following is an example of a ForecastingSettings component that enables the Opportunity-Revenue and Product Family-Quantity forecast types:

1<?xml version="1.0" encoding="UTF-8"?>
2<ForecastingSettings xmlns="http://soap.sforce.com/2006/04/metadata">
3    <enableForecasts>true</enableForecasts>
4    <forecastingTypeSettings>
5        <active>true</active>
6        <adjustmentsSettings>
7            <enableAdjustments>true</enableAdjustments>
8        </adjustmentsSettings>
9        <name>OpportunityRevenue</name>
10        <forecastRangeSettings>
11            <beginning>0</beginning>
12            <displaying>6</displaying>
13            <periodType>Month</periodType>
14        </forecastRangeSettings>
15        <opportunityListFieldsSelectedSettings>
16            <field>OPPORTUNITY.NAME</field>
17        </opportunityListFieldsSelectedSettings>
18        <quotasSettings>
19            <showQuotas>true</showQuotas>
20        </quotasSettings>
21    </forecastingTypeSettings>
22    <forecastingTypeSettings>
23        <active>false</active>
24        <adjustmentsSettings>
25            <enableAdjustments>true</enableAdjustments>
26        </adjustmentsSettings>
27        <name>OpportunityLineItemQuantity</name>
28        <forecastRangeSettings>
29            <beginning>0</beginning>
30            <displaying>6</displaying>
31            <periodType>Month</periodType>
32        </forecastRangeSettings>
33        <opportunityListFieldsSelectedSettings>
34            <field>OPPORTUNITY.NAME</field>
35        </opportunityListFieldsSelectedSettings>
36        <quotasSettings>
37            <showQuotas>true</showQuotas>
38        </quotasSettings>
39        <displayedCategoryApiNames>pipelineonly</displayedCategoryApiNames>
40        <displayedCategoryApiNames>bestcaseonly</displayedCategoryApiNames>
41        <displayedCategoryApiNames>commitonly</displayedCategoryApiNames>
42        <displayedCategoryApiNames>closedonly</displayedCategoryApiNames>
43        <forecastedCategoryApiNames>commitonly</forecastedCategoryApiNames>
44        <forecastedCategoryApiNames>closedonly</forecastedCategoryApiNames>
45        <forecastedCategoryApiNames>bestcaseonly</forecastedCategoryApiNames>
46        <forecastedCategoryApiNames>pipelineonly</forecastedCategoryApiNames>
47        <managerAdjustableCategoryApiNames>commitonly</managerAdjustableCategoryApiNames>
48        <managerAdjustableCategoryApiNames>bestcaseonly</managerAdjustableCategoryApiNames>
49        <ownerAdjustableCategoryApiNames>commitonly</ownerAdjustableCategoryApiNames>
50        <ownerAdjustableCategoryApiNames>bestcaseonly</ownerAdjustableCategoryApiNames>
51    </forecastingTypeSettings>
52    <forecastingCategoryMappings>
53        <forecastingItemCategoryApiName>commitonly</forecastingItemCategoryApiName>
54        <weightedSourceCategories>
55            <sourceCategoryApiName>commit</sourceCategoryApiName>
56            <weight>1.0</weight>
57        </weightedSourceCategories>
58    </forecastingCategoryMappings>
59    <forecastingCategoryMappings>
60        <forecastingItemCategoryApiName>closedonly</forecastingItemCategoryApiName>
61        <weightedSourceCategories>
62            <sourceCategoryApiName>closed</sourceCategoryApiName>
63            <weight>1.0</weight>
64        </weightedSourceCategories>
65    </forecastingCategoryMappings>
66    <forecastingCategoryMappings>
67        <forecastingItemCategoryApiName>bestcaseforecast</forecastingItemCategoryApiName>
68        <weightedSourceCategories>
69            <sourceCategoryApiName>commit</sourceCategoryApiName>
70            <weight>1.0</weight>
71        </weightedSourceCategories>
72        <weightedSourceCategories>
73            <sourceCategoryApiName>best case</sourceCategoryApiName>
74            <weight>1.0</weight>
75        </weightedSourceCategories>
76        <weightedSourceCategories>
77            <sourceCategoryApiName>closed</sourceCategoryApiName>
78            <weight>1.0</weight>
79        </weightedSourceCategories>
80    </forecastingCategoryMappings>
81    <forecastingCategoryMappings>
82        <forecastingItemCategoryApiName>omittedonly</forecastingItemCategoryApiName>
83        <weightedSourceCategories>
84            <sourceCategoryApiName>omitted</sourceCategoryApiName>
85            <weight>1.0</weight>
86        </weightedSourceCategories>
87    </forecastingCategoryMappings>
88    <forecastingCategoryMappings>
89        <forecastingItemCategoryApiName>openpipeline</forecastingItemCategoryApiName>
90        <weightedSourceCategories>
91            <sourceCategoryApiName>commit</sourceCategoryApiName>
92            <weight>1.0</weight>
93        </weightedSourceCategories>
94        <weightedSourceCategories>
95            <sourceCategoryApiName>best case</sourceCategoryApiName>
96            <weight>1.0</weight>
97        </weightedSourceCategories>
98        <weightedSourceCategories>
99            <sourceCategoryApiName>pipeline</sourceCategoryApiName>
100            <weight>1.0</weight>
101        </weightedSourceCategories>
102    </forecastingCategoryMappings>
103    <forecastingCategoryMappings>
104        <forecastingItemCategoryApiName>bestcaseonly</forecastingItemCategoryApiName>
105        <weightedSourceCategories>
106            <sourceCategoryApiName>best case</sourceCategoryApiName>
107            <weight>1.0</weight>
108        </weightedSourceCategories>
109    </forecastingCategoryMappings>
110    <forecastingCategoryMappings>
111        <forecastingItemCategoryApiName>commitforecast</forecastingItemCategoryApiName>
112        <weightedSourceCategories>
113            <sourceCategoryApiName>closed</sourceCategoryApiName>
114            <weight>1.0</weight>
115        </weightedSourceCategories>
116        <weightedSourceCategories>
117            <sourceCategoryApiName>commit</sourceCategoryApiName>
118            <weight>1.0</weight>
119        </weightedSourceCategories>
120    </forecastingCategoryMappings>
121    <forecastingCategoryMappings>
122        <forecastingItemCategoryApiName>pipelineonly</forecastingItemCategoryApiName>
123        <weightedSourceCategories>
124            <sourceCategoryApiName>pipeline</sourceCategoryApiName>
125            <weight>1.0</weight>
126        </weightedSourceCategories>
127    </forecastingCategoryMappings>

Wildcard Support in the Manifest File

The wildcard character * (asterisk) in the package.xml manifest file doesn’t apply to metadata types for feature settings. The wildcard applies only when retrieving all settings, not for an individual setting. For details, see Settings. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.

Metadata API Developer Guide