ForecastingSettings

Represents the Collaborative Forecasts settings options. This type extends the Metadata metadata type and inherits its fullName field.

This information only applies to Collaborative Forecasts.

Note

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 is 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)	The currency for displaying forecasts; either the organization's corporate currency or each forecast owner's personal currency setting. This is the default currency 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`
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 the online Help before disabling any functionality. Warning
forecastingCategoryMappings	ForecastingCategoryMappings[]	A list of mappings associating forecast types with forecast rollups.
forecastingDisplayedFamilySettings	string 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.

ForecastingTypeSettings

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

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	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 may not appear immediately. An in-process icon appears to indicate that the values are being calculated. Note
adjustmentsSettings	AdjustmentsSettings	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)	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	The default periods and range selections in Collaborative Forecasts.
hasProductFamily	boolean	Indicates whether the forecasting type has product family forecasts enabled. Available in API version 41.0 and later.
isAmount	boolean	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	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	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	This read-only field indicates the UI label for the forecast type.
name	string	The name of the forecast type. Each forecast type requires a specific string. Valid values include: `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. `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. `OpportunitySplitRevenue` : Opportunity Revenue Splits - Revenue `OpportunityOverlayRevenue` : Opportunity Overlay Splits - Revenue `OpportunityLineItemRevenue` : Product Families - Revenue `OpportunityLineItemQuantity` : Product Families - Quantity 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	OpportunityListFieldsLabelMappings	A read-only list of the API names and UI labels for all fields on the Opportunity object.
opportunityListFieldsSelectedSettings	OpportunityListFieldsSelectedSettings	The fields selected to appear in the opportunity pane of the forecast page for the forecast type. Opportunity Name is required. You can select up to 15 fields.
opportunityListFieldsUnselectedSettings	OpportunityListFieldsUnselectedSettings	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	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	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	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 12 months or eight quarters in the future or past. If your forecast range includes the current month or quarter, the forecasts page displays the current month or quarter by default. If not, the first month 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	Indicates the beginning month or quarter to display by default.
displaying	int	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)	Indicates what type of period to use. Valid values are: `Month` `Quarter`

OpportunityListFieldsLabelMappings

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

Field	Field Type	Description
field	string	The API name of the Opportunity field.
label	string	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. Opportunity Name is required. 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	Set to `true` to enable quotas. All forecast types must contain the same showQuotas field value.

ForecastingCategoryMappings

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.

Field	Field Type	Description
forecastingItemCategoryApiName	string	This field specifies the API name of the rollup type. The valid values are: openpipeline bestcaseforecast commitforecast pipelineonly bestcaseonly commitonly closedonly omittedonly
weightedSourceCategories	WeightedSourceCategories[]	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

WeightedSourceCategories

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	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	Specifies the weight given to the forecast category when calculating the forecast for the rollup type. The only supported value is 1.0.

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.

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>

Metadata API Developer Guide