CustomHelpMenuSection Metadata Type in SFDX

Architectural Overview#

The CustomHelpMenuSection metadata type represents the org-specific custom resource section inside the Lightning Experience global Help Menu (the question-mark icon in the top navigation bar). In enterprise Salesforce deployments, user adoption and self-service support depend on surfacing internal runbooks, Confluence pages, ServiceNow ticket portals, and WalkMe or Trailhead modules right where users work.

By managing CustomHelpMenuSection declaratively in version control, Release Managers ensure that sandbox refreshes and production cutovers consistently point users to the right support channels without post-deployment manual configuration.

SFDX Directory and File Suffix#

Key Metadata Fields#

The CustomHelpMenuSection metadata type extends Metadata and contains the following fields:

CustomHelpMenuItem Subtype Fields#

Declarative XML and package.xml Examples#

Source Format XML (CustomHelpMenuSection.customHelpMenuSection-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<CustomHelpMenuSection xmlns="http://soap.sforce.com/2006/04/metadata">
    <customHelpMenuItems>
        <linkUrl>https://intranet.example.com/salesforce-sales-playbook</linkUrl>
        <masterLabel>Global Sales Playbook &amp; SOPs</masterLabel>
        <sortOrder>1</sortOrder>
    </customHelpMenuItems>
    <customHelpMenuItems>
        <linkUrl>https://servicedesk.example.com/create-crm-ticket</linkUrl>
        <masterLabel>Log a CRM Support Ticket</masterLabel>
        <sortOrder>2</sortOrder>
    </customHelpMenuItems>
    <customHelpMenuItems>
        <linkUrl>https://trailhead.salesforce.com</linkUrl>
        <masterLabel>Salesforce Trailhead Learning</masterLabel>
        <sortOrder>3</sortOrder>
    </customHelpMenuItems>
    <masterLabel>Enterprise CRM Resources</masterLabel>
</CustomHelpMenuSection>

Manifest (package.xml)#

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

SFDX CLI Retrieval and Tooling API Inspection#

You can retrieve and deploy CustomHelpMenuSection using standard sf CLI commands or inspect items via Tooling API:

# Retrieve CustomHelpMenuSection metadata into your SFDX project
sf project retrieve start --metadata CustomHelpMenuSection

# Deploy updated help menu links to the target org
sf project deploy start --metadata CustomHelpMenuSection

You can also query CustomHelpMenuSection and CustomHelpMenuItem using the Tooling API:

SELECT Id, DeveloperName, MasterLabel
FROM CustomHelpMenuSection

SELECT Id, MasterLabel, LinkUrl, SortOrder, ParentId
FROM CustomHelpMenuItem
ORDER BY SortOrder ASC

Architect Best Practices and Gotchas#

• Pair with PathAssistantSettings / UserEngagementSettings: While CustomHelpMenuSection stores the items, the section header label and toggle for hiding standard Salesforce help content are managed via org-level engagement settings. Include both in your deployment manifest.
• Contiguous sortOrder Sequence: Always number sortOrder sequentially starting from 1 with no duplicate numbers, up to a maximum of 15 items.
• Environment-Specific Help Portals: If your UAT sandbox should link to a staging knowledge base or UAT bug-reporting form, use SFDX string replacements (sfdx-project.json replacements) on <linkUrl> during CI/CD builds.

Frequently asked questions

How many custom help menu items can be configured in CustomHelpMenuSection?

A Salesforce org can include a single CustomHelpMenuSection containing up to 15 customHelpMenuItems, each pointing to an external HTTPS URL or an internal Salesforce resource.

Where are CustomHelpMenuSection files stored in SFDX source format?

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

What is the relationship between CustomHelpMenuSection and UserEngagementSettings?

CustomHelpMenuSection defines the links and items, while UserEngagementSettings or Lightning Experience Help Menu settings control the custom section title and visibility.

Can CustomHelpMenuSection links be restricted by user profile?

No, CustomHelpMenuSection is an org-wide global help menu configuration. All users in Lightning Experience see the custom section, though target resources can enforce their own authentication.