PathAssistantSettings in SFDX

Architectural Overview#

The PathAssistantSettings metadata type represents the global feature switch governing Lightning Path in Salesforce. Lightning Path visually guides sales and service representatives through stages of a business process (such as Lead qualification, Opportunity closing, or Case escalation) with step-by-step guidance and key field prompts.

While individual path definitions are stored in PathAssistant metadata records, PathAssistantSettings provides the org-wide prerequisite activation. In automated CI/CD and scratch org provisioning pipelines, failing to deploy PathAssistant.settings-meta.xml before deploying FlexiPage components or individual PathAssistant definitions causes deployment errors stating that Path is not enabled in the target subscriber org.

Directory and File Conventions#

In SFDX source format, PathAssistantSettings is stored in the settings/ directory and referenced as Settings:PathAssistant.

Key Metadata Fields#

The XML schema of PathAssistantSettings contains flags managing global path behavior:

Declarative XML and Package Manifest Examples#

Below is a declarative PathAssistant.settings-meta.xml enabling Lightning Path:

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

Scratch Org Definition Configuration#

Enable Path Assistant inside developer scratch orgs:

{
  "orgName": "Sales Cloud Path Dev Org",
  "edition": "Enterprise",
  "settings": {
    "pathAssistantSettings": {
      "pathAssistantEnabled": true,
      "canSubtypeIncludeCollapsePath": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage PathAssistantSettings using Salesforce CLI:

# Retrieve PathAssistantSettings from the target environment
sf project retrieve start --metadata Settings:PathAssistant

# Deploy PathAssistantSettings to remote org
sf project deploy start --metadata Settings:PathAssistant

# Validate settings deployment
sf project deploy validate --metadata Settings:PathAssistant

Architect Best Practices and Gotchas#

• Deployment Sequencing: Always include Settings:PathAssistant in the foundational package tier. If a FlexiPage referencing the runtime_sales_pathassistant:pathAssistant component is deployed prior to PathAssistantSettings, the deployment will fail.
• Picklist Value Dependencies: Individual paths depend on picklist fields. If picklist values are renamed or deactivated, paths referencing those values will fail validation, even if pathAssistantEnabled remains true.
• Mobile Experience Consistency: Path guidance is responsive and renders on Salesforce Mobile. Ensure custom guidance rich text blocks do not contain fixed-width tables that break small-screen rendering.

Frequently asked questions

What does PathAssistantSettings configure in Salesforce?

It enables org-wide Lightning Path functionality, stage guidance panels, and celebration confetti on reaching critical milestone stages.

Where is PathAssistantSettings located in an SFDX workspace?

It is located at force-app/main/default/settings/PathAssistant.settings-meta.xml and retrieved as Settings:PathAssistant.

Why is PathAssistantSettings essential for PathAssistant deployments?

Individual PathAssistant metadata configurations cannot be deployed or displayed unless pathAssistantEnabled is true in PathAssistantSettings.

Can celebratory animations be turned on or off globally via metadata?

Yes. Setting canSubtypeIncludeCollapsePath and related display properties controls user interface animations and stage collapsing behaviors.