CustomFieldDisplay Metadata Type in SFDX

Architectural Overview#

When deploying predictive machine learning models in Einstein Discovery (CRM Analytics / Einstein Studio), architects often configure Automated Prediction Fields so predicted outcomes—such as Predicted Propensity to Buy, Attrition Risk Score, or Invoice Late Payment Probability—are stored directly on the sObject record and sortable in standard List Views and Reports.

The CustomFieldDisplay metadata type controls how these AI-powered fields render in the Salesforce user interface, linking the underlying CustomField to its predictive display metadata (displayType, modelName, and display formatting rules). By committing CustomFieldDisplay artifacts into SFDX version control, DevOps teams can promote predictive field UI configurations alongside their CustomField and AIApplication / MLPredictionDefinition metadata.

SFDX Directory and File Suffix#

Key Metadata Fields#

CustomFieldDisplay binds a target custom field to its predictive display configuration and label settings.

Declarative XML Example#

Below is an example Opportunity_Win_Score_Display.customFieldDisplay-meta.xml binding the Opportunity.Predicted_Win_Score__c field to the Enterprise_Win_Propensity_Model prediction definition.

<?xml version="1.0" encoding="UTF-8"?>
<CustomFieldDisplay xmlns="http://soap.sforce.com/2006/04/metadata">
    <customField>Opportunity.Predicted_Win_Score__c</customField>
    <displayType>DiscoveryPrediction</displayType>
    <isActive>true</isActive>
    <masterLabel>Opportunity Predicted Win Score Display</masterLabel>
    <modelName>Enterprise_Win_Propensity_Model</modelName>
</CustomFieldDisplay>

package.xml Manifest#

Deploy CustomFieldDisplay together with the target CustomField:

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

SFDX CLI Retrieval and Deployment#

Retrieve and deploy CustomFieldDisplay metadata using the sf CLI:

# Retrieve all CustomFieldDisplay configurations from the org
sf project retrieve start --metadata CustomFieldDisplay

# Deploy a specific CustomFieldDisplay component
sf project deploy start \
  --metadata CustomField:Opportunity.Predicted_Win_Score__c \
  --metadata CustomFieldDisplay:Opportunity_Win_Score_Display

Architect Best Practices and Gotchas#

• License & Permission Requirements: Users viewing the enriched DiscoveryPrediction popover on List Views or Record Pages require the View Einstein Discovery Recommendations permission (granted via CRM Analytics Plus or Einstein Predictions permission sets). Users without this permission still see the raw numeric value if granted standard Field-Level Security (FLS) on the CustomField.
• Promote Model Definitions Alongside Field Displays: If modelName references an Einstein Discovery prediction definition that has not yet been deployed to the target sandbox, deployment of CustomFieldDisplay will fail due to an unresolved model reference.

Frequently asked questions

What is the purpose of CustomFieldDisplay in Salesforce?

CustomFieldDisplay defines the visual display configuration for custom fields that store Einstein Discovery predictions, allowing record pages and list views to render prediction scores along with top contributing factors.

Where are CustomFieldDisplay files stored in an SFDX project?

They are stored in force-app/main/default/customFieldDisplays/ with the file suffix .customFieldDisplay-meta.xml.

How does CustomFieldDisplay connect to a CustomField?

A CustomFieldDisplay component links an AI prediction model deployment to a specific custom field used for automated prediction writeback on a standard or custom object.

When should architects use CustomFieldDisplay vs the Einstein Discovery Lightning component?

Use CustomFieldDisplay when predictions are written back to a dedicated custom field for sorting in list views, reports, and compact layouts while still surfacing predictive explanations.