Prompt | Metadata API Developer Guide

File Suffix and Directory Location

Prompt components have the suffix prompt and are stored in the prompts folder.

Version

Prompt components are available in API version 46.0 and later.

Special Access Rules

Admins have access to add or edit prompts and walkthroughs. For non-admin users, assign the Manage Prompts user permission. Everyone can see the In-App Guidance setup page. To show more than three walkthroughs to users, use the View Walkthroughs user permission, which is part of the Walkthroughs permission set license. The myTrailhead subscription includes this feature. For pricing details, contact your Salesforce account executive. Note the restrictions on user visibility of the walkthroughs you create in the Packaging Prompts and Walkthroughs section.

Packaging Prompts and Walkthroughs

See Creating Managed Packages in Salesforce Help for more information.

See Considerations for Prompts in Lightning Experience in Salesforce Help for more information about installing and managing prompt packages and about editing and cloning prompts installed from packages.

If the package includes a custom profile that isn’t part of a Salesforce org, the in-app guidance is installed, but it doesn't include those custom items. For example, an org installs a prompt with several custom profiles not included in their org. The prompts are installed without those custom profiles.

If the package includes a custom permission that isn’t a part of your Salesforce org, the installation fails.

If the package includes a standard app that isn’t part of a Salesforce org, the in-app guidance is installed, but it's not usable.

Unmanaged packages must contain a namespace prefix. For more information, see Register a Namespace Prefix and What happens to my namespace prefix when I install a package? in Salesforce Help.

For walkthrough packages:

If a managed or unmanaged package includes walkthroughs for standard apps, walkthroughs are installed. However, production orgs can have only three active walkthroughs at a time without subscribing to myTrailhead.
If a security-reviewed, first-generation managed package includes walkthroughs with at least one step on a page within a custom app, users can see the walkthroughs without a subscription to myTrailhead.

When orgs install in-app guidance from packages, the in-app guidance will retain publish state as indicated by the IsPublished field. For example, if the package prompt is active, it will also be active when installed by the org.

Fields

Field Name	Field Type	Description
masterLabel	string	Required. The master label. Maximum of 80 characters.
promptVersions	PromptVersion[]	A list of in-app guidance entries. Each entry represents a different prompt or walkthrough.

PromptVersion

A list of in-app guidance entries. Each entry represents a different prompt or walkthrough.

Field Name	Field Type	Description
actionButtonLabel	string	Label for the action button or link. Maximum of 25 characters. For walkthroughs, this field can only be specified on the last step.
actionButtonLink	string	URL for the action button or link. Maximum of 1,000 characters. You can’t use the `GROUP BY` option in a SOQL query for this field. For walkthroughs, this field can only be specified on the last step.
body	string	Required. Body content. For floating prompts, there’s a maximum of 240 characters. For docked prompts, there’s a maximum of 4000 characters. Because the docked prompt has a rich text editor, the maximum characters refer to HTML markup, not readable text.
customApplication	string	Internal use only. No data is populated for this field.
delayDays	int	Required if recurrences are scheduled. Number of days in between occurrences. For walkthroughs, this field can only be specified on the first step.
description	string	Description. Maximum of 255 characters.
dismissButtonLabel	string	Label for the dismiss button of a floating prompt. Maximum of 15 characters.
displayPosition	PromptDisplayPosition (enumeration of type string)	Indicates the position of the floating prompt on the page. Valid values are: `BottomCenter` `BottomLeft` `BottomRight` `TopCenter` `TopLeft` `TopRight`
displayType	PromptDisplayType (enumeration of type string)	Required. Indicates the type of prompt. Valid values are: `DockedComposer`, which is the docked prompt `FloatingPanel`, which is the floating prompt `Targeted` (beta), which is the targeted prompt. Available in API version 52.0 and later.
elementRelativePosition	PromptElementRelativePosition (enumeration of type string)	(Beta) Indicates the location of the prompt relative to the element. Available in API version 52.0 and later. Valid values are: `BottomCenter` `BottomLeft` `BottomRight` `LeftBottom` `LeftCenter` `LeftTop` `RightBottom` `RightCenter` `RightTop` `TopCenter` `TopLeft` `TopRight`
endDate	date	Indicates the date to stop showing the in-app guidance. For walkthroughs, this field can only be specified on the first step.
header	string	Label for the header of the docked prompt. This is the label contained in the window’s browser bar. Maximum of 36 characters.
image	string	The developer name of the contentAsset that holds the image. You can specify this field or the `image` field, but not both.
imageAltText	string	Indicates the alt text of an image, which helps make images accessible. Required if `imageLocation` or `image` is specified.
imageLocation	picklist	Indicates the location of the image in relation to the body text. Required if `image` or `imageAltText` is specified. Valid values are: `Top` `Bottom` `Right`, which is for floating prompts only `Left`, which is for floating prompts only
indexWithIsPublished	string	Used by Salesforce for efficient querying.
indexWithoutIsPublished	string	Used by Salesforce for efficient querying.
isPublished	boolean	Indicates if active `true` or not `false`.
masterLabel	string	Required. The master label.
publishedByUser	string	Internal use only. No data is populated for this field.
publishedDate	date	Indicates the date the in-app guidance was activated. If installed from a package, this is the date when the package was installed. For walkthroughs, this field can only be specified on the first step.
referenceElementContext	textarea	(Beta) Used by Salesforce to identify the element that the targeted prompt is associated with. Available in API version 52.0 and later.
shouldDisplayActionButton	boolean	Indicates if an action button or link is included `true` or not `false`.
shouldIgnoreGlobalDelay	boolean	Indicates if the in-app guidance ignores the global time delay and instead shows on page load `true` or not `false`. This field is available in API version 48.0 and later.
startDate	date	Indicates the date to start showing the in-app guidance. For walkthroughs, this field can only be specified on the first step. In API version 48.0 and earlier, this field is required.
stepNumber	int	Required for walkthroughs only. Indicates the number of the last step the user viewed or interacted with in a walkthrough. Maximum of 10 steps. Numbers must be consecutive without repeated or skipped numbers. Available in API version 49.0 and later.
targetAppDeveloperName	string	The app’s developer name where the in-app guidance appears. Deprecated in API version 51.0 and later.
targetAppNamespacePrefix	string	The app’s namespace prefix where the in-app guidance appears. Must match the target app’s `NamespacePrefix` in the org that the package is being installed into. Maximum of 15 characters. Deprecated in API version 51.0 and later.
targetPageKey1	string	Required. Used by Salesforce to identity the page location along with `targetPageKey2` and `targetPageType`.
targetPageKey2	string	Used by Salesforce to identity the page location along with `targetPageKey1` and `targetPageType`.
targetPageType	string	Required. Used by Salesforce to identity the page location along with `targetPageKey1` and `targetPageKey2`.
themeColor	PromptThemeColor (enumeration of type string)	Indicates which custom theme color is applied to in-app guidance. Required if themeSaturation is specified. Specify on the first step of the walkthrough to apply to the entire walkthrough. Valid values are: `Theme1`, which is derived from the current brand color `Theme2`, which is derived from the current page background color `Theme3`, which is derived from the current global header color `Theme4`, which is derived from the current app theme color
themeSaturation	PromptThemeSaturation (enumeration of type string)	Indicates which color value, or saturation, is applied to in-app guidance that has a custom theme color applied. Required if themeColor is specified. Specify on the first step of the walkthrough to apply to the entire walkthrough. Valid values are: `Dark` `Light`
timesToDisplay	int	Required if recurrences are scheduled. Maximum number of times to display the in-app guidance (that is, the number of occurrences). Salesforce detects if the user interacts with (or ignores) the in-app guidance to determine if we should show the in-app guidance again or cancel scheduled recurrences. This might run counter to the number of occurrences scheduled. Maximum value of 30. For walkthroughs, this field can only be specified on the first step.
title	string	Required. The label for the title. Maximum of 36 characters.
uiFormulaRule	UiFormulaRule	A set of one or more permission filters that define the conditions under which the in-app guidance displays on the page. If the rule evaluates to `true`, the in-app guidance displays on the page. If `false`, it doesn't display. If this field is `null`, the in-app guidance displays by default.
userAccess	PromptUserAccess (enumeration of type string)	Indicates which permissions can see the in-app guidance. Valid values are: `Everyone`, which indicates that there’s no permission restrictions `SpecificPermissions`, which indicates that only users with all the specific user permissions specified can see the in-app guidance In API version 48.0 and earlier, this field is required.
userProfileAccess	PromptUserProfileAccess (enumeration of type string)	Indicates which profiles can see the in-app guidance. This field is available in API version 48.0 and later. Valid values are: `Everyone`, which indicates that there are no profile restrictions `SpecificProfiles`, which indicates that users with any of the specified user profiles can see the in-app guidance
versionNumber	int	Required. The number remains `1` since multiple versions aren’t saved in the org.
videoLink	string	The URL for the video in a docked prompt. Maximum of 1,000 characters. You can specify this field or the `image` field, but not both. This field is available in API version 48.0 and later. To find the embed code for a video, follow the instructions from the video host website. Usually the steps can be found by searching for the name of the website and “embed video.” For example, here’s what the embed code looks like for YouTube: `<iframe width="560" height="315" src="https://www.youtube.com/embed/di6iwHhrH6s" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>` Then, you would enter the URL found in the `src` attribute. For the example used, enter `https://www.youtube.com/embed/di6iwHhrH6s`.

UiFormulaRule

A set of one or more filters that define the conditions under which a prompt displays on a Lightning page.

Field Name	Field Type	Description
booleanFilter	string	Specifies the AND filter condition.
criteria	UiFormulaCriterion[]	List of one or more filters that, when evaluated, determine visibility.

UiFormulaCriterion

A single filter that, when evaluated, helps define visibility on a Lightning page.

Field Name	Field Type	Description
leftValue	string	Required. The field upon which the filter is based. Only standard and custom permissions can be included. You can use these expressions in the leftValue field when setting filters for visibility. `{!$Permission.CustomPermission.permissionName}`—Use this expression to control visibility based on the custom permissions of the user viewing the Lightning page. Supported for app, Home, and record pages only. `{!$Permission.StandardPermission.permissionName}`—Use this expression to control visibility based on the standard permissions of the user viewing the Lightning page. Supported for app, Home, and record pages only. `{!ENCODED:{!ID:$User.Profile.Key}}`—Use this expression to control visibility based on the custom or standard profile of the user viewing the Lightning page. Available in API Version 48.0 and later.
operator	string	Required. Defines the operator used to filter the data. Valid value is `EQUAL`.
rightValue	string	Specifies if you want to evaluate the visibility for permissions or the name of the profile. For permissions, use `true`. For profiles, use the name of the profile. Available in API Version 48.0 and later. For example, `Standard`or `custom_regionalsales`.

Declarative Metadata Sample Definition

The following is an example of a Prompt component.

1<?xml version="1.0" encoding="UTF-8"?>
2<Prompt xmlns="http://soap.sforce.com/2006/04/metadata">
3    <masterLabel>Prompt Master Label</masterLabel>
4    <promptVersions>
5        <actionButtonLabel>Learn How</actionButtonLabel>
6        <actionButtonLink>https://trailhead.salesforce.com/en/content/learn/modules/scrum-and-kanban-at-salesforce/learn-about-kanban</actionButtonLink>
7        <body>Explore how the Path and the Kanban view can help you track, manage, and update your records.</body>
8        <delayDays>1</delayDays>
9        <description>Kanban floating prompt</description>
10        <dismissButtonLabel>OK</dismissButtonLabel>
11        <displayPosition>TopLeft</displayPosition>
12        <displayType>FloatingPanel</displayType>
13        <endDate>2019-03-11</endDate>
14        <isPublished>true</isPublished>
15        <masterLabel>Prompt Master Label</masterLabel>
16        <publishedDate>2019-03-11</publishedDate>
17        <shouldDisplayActionButton>false</shouldDisplayActionButton>
18        <shouldIgnoreGlobalDelay>false</shouldIgnoreGlobalDelay>
19        <startDate>2019-03-11</startDate>
20        <targetAppDeveloperName>LightningSales</targetAppDeveloperName>
21        <targetAppNamespacePrefix>standard</targetAppNamespacePrefix>
22        <timesToDisplay>3</timesToDisplay>
23        <title>Get on the Path to Success</title>
24        <userAccess>SpecificPermissions</userAccess>
25        <userProfileAccess>SpecificProfiles</userProfileAccess>
26        <versionNumber>1</versionNumber>
27        <videolink>https://www.youtube.com/embed/Ko-gcObzTVo</videolink>
28        <uiFormulaRule>
29            <booleanFilter>(1 AND 2 AND 3) AND (4 OR 5)</booleanFilter>
30            <criteria>
31                <leftValue>{!$Permission.StandardPermission.ActivitiesAccess}</leftValue>
32                <operator>EQUAL</operator>
33                <rightValue>TRUE</rightValue>
34            </criteria>
35            <criteria>
36                <leftValue>{!$Permission.StandardPermission.ContentWorkspaces}</leftValue>
37                <operator>EQUAL</operator>
38                <rightValue>TRUE</rightValue>
39            </criteria>
40            <criteria>
41                <leftValue>{!$Permission.CustomPermission.MyCustomPerm}</leftValue>
42                <operator>EQUAL</operator>
43                <rightValue>TRUE</rightValue>
44            </criteria>
45            <criteria>
46                <leftValue>{!ENCODED:{!ID:$User.Profile.Key}}</leftValue>
47                <operator>EQUAL</operator>
48                <rightValue>Standard</rightValue>
49            </criteria>
50            <criteria>
51                <leftValue>{!ENCODED:{!ID:$User.Profile.Key}}</leftValue>
52                <operator>EQUAL</operator>
53                <rightValue>custom_mysysadmin</rightValue>
54            </criteria>
55        </uiFormulaRule>
56    </promptVersions>
57</Prompt>

The following is an example package.xml that references the previous definition.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>Prompt</name>
6    </types>
7    <version>46.0</version>
8</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.