ProfileActionOverride Metadata in SFDX

Architectural Overview#

Standard Salesforce record actions—such as New, Edit, View, and Tab—provide out-of-the-box modal dialogues and record views. However, in sophisticated enterprise systems, different user roles require tailored interaction models. For instance, customer service representatives may need a guided wizard for creating Cases, while back-office operations require a compact, bulk-entry layout.

The ProfileActionOverride metadata type allows architects to map standard record actions to custom Lightning Web Components (LWCs), Aura components, or FlexiPage metadata based on the user’s assigned Profile and device form factor (Desktop vs. Mobile).

By maintaining profile-specific overrides in source control, architects ensure tailored user experiences are delivered consistently without brittle URL hacking or custom redirect controllers.

Directory and File Conventions#

ProfileActionOverride elements are embedded directly within Profile metadata files or managed in action override structures:

Key Metadata Fields#

The XML structure of ProfileActionOverride defines the target action and component binding:

Declarative XML and Package Manifest Examples#

Below is an XML snippet embedded inside a Profile metadata file:

<?xml version="1.0" encoding="UTF-8"?>
<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <custom>true</custom>
    <profileActionOverrides>
        <actionName>New</actionName>
        <content>Case_Creation_Wizard_Page</content>
        <formFactor>Large</formFactor>
        <pageOrSobjectType>Case</pageOrSobjectType>
        <type>Flexipage</type>
    </profileActionOverrides>
    <profileActionOverrides>
        <actionName>Edit</actionName>
        <content>caseEditLwc</content>
        <formFactor>Large</formFactor>
        <pageOrSobjectType>Case</pageOrSobjectType>
        <type>LightningComponent</type>
    </profileActionOverrides>
</Profile>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage profile action overrides via the Salesforce CLI:

# Retrieve profiles including action overrides
sf project retrieve start --metadata Profile:Support_Agent

# Deploy profile alongside target FlexiPage
sf project deploy start --metadata "Profile:Support_Agent" --metadata "FlexiPage:Case_Creation_Wizard_Page"

# Validate deployment into sandbox
sf project deploy validate --metadata Profile:Support_Agent

Architect Best Practices and Gotchas#

• Component Availability: If the referenced LWC or FlexiPage does not exist in the target org, profile deployment fails with Content does not exist. Ensure complete dependency manifests.
• Form Factor Parity: If an override is configured for Large (Desktop) but omitted for Small (Mobile), mobile users will see the standard mobile record layout, creating behavioral discrepancies.
• Permission Sets vs. Profiles Strategy: While permission sets are preferred for permissions, action overrides bound to profiles remain a valid pattern when different business personas require completely different screen interactions.

Frequently asked questions

What is the architectural purpose of ProfileActionOverride?

It routes standard object actions such as New, Edit, or View to custom Lightning components or FlexiPages specifically tailored by user profile.

Where is ProfileActionOverride defined in an SFDX project?

It is defined within Profile metadata files under the profileActionOverrides tag, or managed alongside custom object action overrides.

What form factors are supported by ProfileActionOverride?

Supported form factors are Large for desktop experiences and Small for Salesforce mobile application navigation.

What happens if a user profile does not have an action override defined?

Salesforce falls back to the object-level standard action override or default Lightning record layout.