HelpSettings Metadata Type in SFDX

Architectural Overview#

HelpSettings is the metadata configuration point for in-app help, Learning Paths, and global Help Menu customization in Salesforce Lightning Experience. Large enterprise organizations customize the Help Menu to direct employees to internal wikis, standard operating procedures (SOPs), support ticketing systems, and tailored Trailhead learning modules.

Deploying HelpSettings through version control ensures that user enablement, onboarding pathways, and internal help desk routing remain synchronized across environments during phased CRM rollouts.

Directory and File Conventions#

HelpSettings is stored in the standard settings directory:

Key Metadata Fields#

The HelpSettings metadata type contains several XML attributes:

Declarative XML and Package Manifest Examples#

Below is a production Help.settings-meta.xml configuration enabling custom help and Learning Paths:

<?xml version="1.0" encoding="UTF-8"?>
<HelpSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableHelpMenu>true</enableHelpMenu>
    <enableLearningPaths>true</enableLearningPaths>
</HelpSettings>

Scratch Org Definition (config/project-scratch-def.json)#

{
  "orgName": "Enterprise User Adoption Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "helpSettings": {
      "enableHelpMenu": true,
      "enableLearningPaths": true
    }
  }
}

Package Manifest (package.xml)#

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

Retrieval and Deployment via SF CLI#

Commands to manage HelpSettings across orgs:

# Retrieve HelpSettings
sf project retrieve start --metadata "Settings:Help"

# Deploy HelpSettings to sandbox
sf project deploy start --metadata "Settings:Help" --target-org staging-sandbox

Senior Architect Best Practices and Gotchas#

• User Guidance Alignment: Ensure in-app help links point to permanent redirection URLs or corporate knowledge bases that remain valid across development life cycles.
• Sandbox Testing: Verify that custom help links pointing to staging internal wikis are properly updated when promoting settings to production.
• Permission Requirements: Ensure users assigned to manage Learning Paths have the corresponding system permissions granted via permission sets.

Frequently asked questions

What core features are controlled by HelpSettings?

HelpSettings controls custom help providers, customized Help Menu links, and Learning Paths enablement for users.

How is HelpSettings retrieved using the Salesforce CLI?

Execute sf project retrieve start with metadata flag set to Settings:Help to retrieve Help.settings-meta.xml.

Can HelpSettings hide standard Salesforce help links?

Yes. Administrators can configure custom help menu sections and suppress standard documentation links.

What happens if a custom help provider URL is invalid?

The settings deploy successfully, but users will encounter broken link errors when clicking help links in the UI.