TrailheadSettings Metadata Type in SFDX

Architectural Overview#

The TrailheadSettings metadata type controls the administrative configuration of Trailhead and Sales Enablement (formerly myTrailhead) inside Salesforce Lightning Experience. As organizations embrace contextual onboarding and continuous learning, Salesforce exposes learning modules directly inside the CRM through the In-App Learning Paths panel and Guidance Center.

From an enterprise governance perspective, TrailheadSettings provides the programmatic switch to enable or restrict corporate learning feeds, track user badge progress against compliance requirements, and bind custom Trailhead subdomains to the CRM tenant. Automating these settings across sandbox and scratch org lifecycles ensures that end-user testing accurately reflects the guided training paths deployed to production.

Directory and File Conventions#

In Salesforce DX project structure, TrailheadSettings is managed as a singleton setting file located in the settings/ directory.

Key Metadata Fields#

The TrailheadSettings type exposes the following configuration elements in XML representation:

Declarative XML and Package Manifest Examples#

Below is a standard declarative XML configuration for enterprise enablement environments:

<?xml version="1.0" encoding="UTF-8"?>
<TrailheadSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableBadgeTracking>true</enableBadgeTracking>
    <enableTrailheadContentSync>true</enableTrailheadContentSync>
    <enableTrailheadInAppLearning>true</enableTrailheadInAppLearning>
</TrailheadSettings>

Scratch Org Configuration (project-scratch-def.json)#

To enable learning panels automatically in ephemeral development environments, include the settings block:

{
  "orgName": "Enablement Dev Org",
  "edition": "Developer",
  "settings": {
    "trailheadSettings": {
      "enableTrailheadInAppLearning": true,
      "enableBadgeTracking": true
    }
  }
}

Manifest Definition (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy TrailheadSettings using standard Salesforce CLI commands:

# Retrieve Trailhead settings from the target org
sf project retrieve start --metadata Settings:Trailhead

# Deploy Trailhead settings to production or staging sandbox
sf project deploy start --metadata Settings:Trailhead --target-org prod-ci

Architect Best Practices and Gotchas#

• Dependency Ordering in CI/CD: Deploy Trailhead.settings-meta.xml before deploying Lightning App Pages or FlexiPages that embed the Learning Paths panel or custom In-App Guidance components.
• License Entitlement Gates: If enableTrailheadContentSync is set to true in an org lacking active Sales Enablement licenses, the metadata deployment may succeed with a warning or fail depending on API release flags.
• Testing Contextual Learning in Scratch Orgs: Ensure that scratch orgs mirror production settings so that functional testers experience the same contextual help panel layout as standard business users.

Frequently asked questions

What does TrailheadSettings control in a Salesforce organization?

It controls org-level configuration for Trailhead integration, including Learning Paths panel display, myTrailhead custom content synchronization, and user badge progress tracking.

How do you retrieve TrailheadSettings using Salesforce CLI?

Execute sf project retrieve start with the metadata flag set to Settings:Trailhead to generate the Trailhead.settings-meta.xml file in the settings directory.

Can TrailheadSettings be configured inside scratch org definitions?

Yes, define trailheadSettings inside the settings block of project-scratch-def.json to automatically activate Learning Paths during scratch org creation.

What happens if Trailhead In-App Learning is disabled in production?

The global Learning Paths panel and Trailhead recommendation widgets are hidden across Lightning Experience, preventing users from accessing assigned modules.