UserProfileSearchScope Metadata Type in SFDX

Architectural Overview#

The UserProfileSearchScope metadata type configures customized search scoping and object prioritization rules tailored to distinct user personas and profiles across Salesforce Lightning Experience. In large-scale enterprises with hundreds of custom and standard objects, default global search behaviors often produce cluttered result sets with irrelevant record types.

A customer support representative primarily searches for Case, Contact, and Asset records, whereas an account executive searches for Lead, Opportunity, and Account. UserProfileSearchScope enables architects to establish declarative search ordering, ensuring that global search and modal lookup dialogs rank business-critical entities at the top of results. Version-controlling these configurations guarantees that search optimizations are systematically applied across release tiers.

Directory and File Conventions#

In the Salesforce DX project repository, UserProfileSearchScope files reside within the userProfileSearchScopes/ directory.

Key Metadata Fields#

The XML schema for UserProfileSearchScope includes the following configuration attributes:

Declarative XML and Package Manifest Examples#

The following declarative XML definition configures search ordering for customer service profiles:

<?xml version="1.0" encoding="UTF-8"?>
<UserProfileSearchScope xmlns="http://soap.sforce.com/2006/04/metadata">
    <entity>Case</entity>
    <isEnabled>true</isEnabled>
    <profile>Custom: Support Profile</profile>
    <sortOrder>1</sortOrder>
</UserProfileSearchScope>

Manifest Definition (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy UserProfileSearchScope with the Salesforce CLI:

# Retrieve all profile search scope definitions
sf project retrieve start --metadata UserProfileSearchScope

# Retrieve a specific search scope configuration
sf project retrieve start --metadata UserProfileSearchScope:Support_Case_Scope

# Deploy search scopes to an integration sandbox
sf project deploy start --metadata UserProfileSearchScope:Support_Case_Scope --target-org staging-sandbox

Architect Best Practices and Gotchas#

• Search Indexing Sync: Updating search scope metadata directs UI presentation; ensure custom fields have appropriate search indexing enabled in the underlying Object Manager.
• Cross-Profile Alignment: Periodically audit search scopes against user feedback to ensure changing business priorities are reflected in global search ranking.
• Deployment Dependencies: Deploy underlying Custom Objects before deploying corresponding UserProfileSearchScope metadata to avoid unresolved entity errors during packaging.

Frequently asked questions

What does UserProfileSearchScope control in Salesforce?

It defines which standard and custom objects appear in global search results and lookup dialogs for specific user profiles, as well as their display order.

How do you retrieve UserProfileSearchScope using Salesforce CLI?

Use sf project retrieve start with the metadata flag set to UserProfileSearchScope to download the search scope XML files into your local project.

Why should architects configure profile-specific search scopes?

Customizing search scopes optimizes user productivity by prioritizing relevant objects (like Cases for support agents or Leads for sales reps) in search results.

Can UserProfileSearchScope be packaged in second-generation packages?

Yes, UserProfileSearchScope metadata can be bundled into 2GP managed and unlocked packages to deliver tailored search experiences to subscribers.