ForecastingObjectListSettings in SFDX

Architectural Overview#

ForecastingObjectListSettings is the metadata type responsible for customizing the opportunity and deal inspection table positioned at the bottom of the Collaborative Forecasts interface. When sales leaders navigate forecast rollups—expanding role hierarchies and reviewing commit totals—clicking a forecast category or rollup cell reveals the list of individual records contributing to that aggregate number.

From an administrative and architectural standpoint, ForecastingObjectListSettings ensures that sales managers have immediate visibility into the specific custom fields that matter during forecast inspections (such as Next Step, ARR, Competitor, or Win Probability). Automating these list settings via Salesforce DX ensures consistent inspection layouts across global enterprise teams.

Directory and File Conventions#

In Salesforce DX source format (apiVersion 68.0), ForecastingObjectListSettings metadata is managed either as independent files in forecastingObjectListSettings/ or bundled within ForecastingSettings.

Key Metadata Fields#

The XML structure governs target forecasting types, sort orders, and displayed field arrays:

Declarative XML and Package Manifest Examples#

Below is a declarative ForecastingObjectListSettings definition tailored for strategic deal reviews:

<?xml version="1.0" encoding="UTF-8"?>
<ForecastingObjectListSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <forecastingType>Enterprise_Revenue</forecastingType>
    <displayedFields>Opportunity.Name</displayedFields>
    <displayedFields>Opportunity.Account.Name</displayedFields>
    <displayedFields>Opportunity.Amount</displayedFields>
    <displayedFields>Opportunity.CloseDate</displayedFields>
    <displayedFields>Opportunity.StageName</displayedFields>
    <displayedFields>Opportunity.NextStep</displayedFields>
    <sortField>Opportunity.Amount</sortField>
    <sortDirection>Descending</sortDirection>
</ForecastingObjectListSettings>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Enterprise_Revenue_List</members>
        <name>ForecastingObjectListSettings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage object list settings via Salesforce CLI:

# Retrieve all forecasting object list settings
sf project retrieve start --metadata ForecastingObjectListSettings

# Deploy list settings to your target environment
sf project deploy start --metadata ForecastingObjectListSettings:Enterprise_Revenue_List

Architect Best Practices and Gotchas#

• Field-Level Security (FLS) Adherence: When declaring columns, ensure that the fields are readable via PermissionSet or Profile configurations. Restricted fields are omitted from display without error.
• Maximum Column Thresholds: Avoid configuring more than 15 columns in displayedFields. Excessive columns degrade UI responsiveness and force horizontal scrolling on mobile and laptop screens.
• Referential Dependency Order: The referenced forecastingType must exist in the target org prior to deploying this metadata asset.

Frequently asked questions

What visual component does ForecastingObjectListSettings configure?

It customizes the opportunity or custom object list view displayed at the bottom of the Collaborative Forecasts grid when sales leaders drill into numbers.

How do field-level security permissions affect ForecastingObjectListSettings?

If a column declared in this metadata is restricted by field-level security, the field is gracefully hidden from unauthorized users in the list view.

Can custom fields on Opportunity Splits be added to ForecastingObjectListSettings?

Yes. Any valid field on the underlying source object, including split fields, can be declared as displayed columns in this metadata configuration.