Prompt Metadata Type in SFDX

Architectural Overview#

User adoption and change management often represent the greatest hurdles to maximizing CRM return on investment. When new features, custom Lightning Web Components, or restructured business processes are introduced, users require contextual, just-in-time training rather than static training manuals.

The Prompt metadata type defines Salesforce In-App Guidance components within Lightning Experience. Prompts can be configured as floating notifications, targeted tooltips anchored directly to specific UI fields or buttons, or multi-step interactive walkthroughs that guide users through end-to-end business workflows.

Managing Prompt definitions as declarative code enables enterprise architects to coordinate user enablement campaigns directly alongside software release cycles in CI/CD pipelines.

Directory and File Conventions#

In SFDX source projects, Prompt metadata files are organized in the prompts/ directory:

Key Metadata Fields#

The XML schema of Prompt encapsulates versioning, display parameters, and targeting criteria:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of a targeted prompt announcing a new deal desk discount calculator:

<?xml version="1.0" encoding="UTF-8"?>
<Prompt xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Deal Desk Calculator Notice</masterLabel>
    <promptVersions>
        <body>Use the new Deal Desk Calculator component to model multi-year tier discounts before submitting for manager approval.</body>
        <delayDays>1</delayDays>
        <displayType>Targeted</displayType>
        <isPublished>true</isPublished>
        <masterLabel>Deal Desk Calculator Notice v1</masterLabel>
        <publishedDate>2026-11-12</publishedDate>
        <shouldDisplayActionButton>true</shouldDisplayActionButton>
        <actionButtonLabel>Launch Training Flow</actionButtonLabel>
        <actionButtonUrl>/flow/Deal_Desk_Onboarding_Flow</actionButtonUrl>
        <targetApp>LightningSales</targetApp>
        <targetPageType>standard__recordPage</targetPageType>
        <timesToDisplay>3</timesToDisplay>
        <title>New Deal Desk Calculator Available</title>
        <userAccess>Everyone</userAccess>
    </promptVersions>
</Prompt>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage Prompt metadata via the Salesforce CLI:

# Retrieve all prompts from the target environment
sf project retrieve start --metadata Prompt

# Deploy a specific prompt alongside referenced flows
sf project deploy start --metadata "Prompt:Deal_Desk_Calculator_Notice" --metadata "Flow:Deal_Desk_Onboarding_Flow"

# Validate prompt deployment into staging sandbox
sf project deploy validate --metadata Prompt

Architect Best Practices and Gotchas#

• UI Element Selector Stability: Targeted prompts bind to specific DOM elements or component wrappers. If a custom LWC or FlexiPage is redesigned, test targeted prompts to ensure the visual anchor still renders accurately.
• Prompt Fatigue Governance: Establish an org-wide In-App Guidance schedule. Overloading end users with simultaneous floating prompts leads to reflexive dismissal without reading.
• License Boundary Checks: Deploying multi-step walkthroughs to scratch orgs lacking InAppGuidanceWalkthrough feature licenses will cause deployment errors.

Frequently asked questions

What types of In-App Guidance are supported by Prompt metadata?

It supports floating prompts, targeted prompts anchored to specific UI components, docked composers, and multi-step walkthroughs.

Where are Prompt metadata files stored in an SFDX source project?

They reside in force-app/main/default/prompts/ with the .prompt-meta.xml file extension.

Can prompts be restricted to specific user profiles or permissions?

Yes, prompts can be targeted globally to all users or scoped to users possessing specific custom permissions or assigned profiles.

How can action buttons inside prompts launch automation?

Action buttons can be configured with URLs that launch screen Flows, open external documentation, or navigate to specific Lightning pages.