ProfileSearchLayouts Metadata in SFDX

Architectural Overview#

Global Search and lookup dialogues represent the primary discovery interface for Salesforce users. However, different organizational roles prioritize different data points: Sales representatives searching for Accounts need to see Annual Revenue, Industry, and Owner, while Compliance officers need Tax ID, Legal Entity Type, and Sanction Status.

The ProfileSearchLayouts metadata type defines profile-specific column presentations for search results, lookup dialogues, and filter fields across standard and custom objects.

Customizing search layouts by profile reduces time-to-record discovery, streamlines user workflows, and optimizes data visibility across business functions.

Directory and File Conventions#

In SFDX source projects, ProfileSearchLayouts metadata is stored in search layout definitions or profile structures:

Key Metadata Fields#

The XML schema of ProfileSearchLayouts defines layout types and displayed fields:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition configuring Case search results for a Service profile:

<?xml version="1.0" encoding="UTF-8"?>
<ProfileSearchLayouts xmlns="http://soap.sforce.com/2006/04/metadata">
    <fields>CaseNumber</fields>
    <fields>Subject</fields>
    <fields>Status</fields>
    <fields>Priority</fields>
    <fields>Contact.Name</fields>
    <profile>Custom_Support_Agent</profile>
</ProfileSearchLayouts>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage ProfileSearchLayouts via the Salesforce CLI:

# Retrieve search layout metadata
sf project retrieve start --metadata ProfileSearchLayouts

# Deploy search layouts to target environment
sf project deploy start --metadata ProfileSearchLayouts

# Validate deployment into sandbox
sf project deploy validate --metadata ProfileSearchLayouts

Architect Best Practices and Gotchas#

• Field Existence Validation: Every field API name specified in <fields> must exist on the target CustomObject. Renaming or deleting a custom field without updating search layouts causes deployment failures.
• Column Density and Readability: Limit search results columns to 6 or 7 key fields. Excessive columns cause horizontal scrolling and degrade readability on compact screens.
• Secondary Fields for Instant Search: Ensure key identifying fields (such as Account Name or Phone) are positioned early in the field list so instant search popovers display meaningful identifiers.

Frequently asked questions

What is the purpose of ProfileSearchLayouts in Salesforce?

It specifies which fields appear in search results, lookup dialogs, and instant search results for users belonging to a specific profile.

Where are ProfileSearchLayouts managed in SFDX projects?

They are managed in search layout configurations or embedded within Profile metadata definitions.

Do ProfileSearchLayouts bypass field-level security?

No, if a user lacks read access to a field included in the search layout, that column is rendered blank or omitted.

Can ProfileSearchLayouts be configured for custom objects?

Yes, profile-specific search layouts are supported for both standard and custom objects in Salesforce.