Prompt | Metadata API Developer Guide

Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

Important

Parent Type

This type extends the Metadata metadata type and inherits its fullName field.

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

To add, edit, manage, and view prompts and walkthroughs in Lightning Experience or in Experience Cloud sites, see Considerations for Creating In-App Guidance and Permissions for Creating and Accessing In-App Guidance in Salesforce Help for permissions.

Prompts and Walkthroughs in Managed Packages

For considerations about including in-app guidance in a managed package, see Guidelines for In-App Guidance in Managed Packages in Salesforce Help.

For more information about creating managed packages, see Create a First-Generation Managed Package.

Unmanaged packages must contain a namespace prefix. For more information, see Register a Namespace for a First-Generation Managed Packages and What happens to my namespace prefix when I install a package?.

Fields

Field Name	Description
masterLabel	Field Type string Description Required. The label. Maximum of 80 characters.
promptVersions	Field Type PromptVersion[] Description 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	Description
actionButtonLabel	Field Type string Description Label for the action button or link. Maximum of 25 characters. For a walkthrough, specify this value on the last step.
actionButtonLink	Field Type string Description 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 a walkthrough, specify this value on the last step.
body	Field Type string Description Required. Body content. In API version 60.0 and later, enter up to 4,000 characters for all prompt types. In earlier API versions, enter up to 240 characters for floating prompts and targeted prompts. Enter up to 4,000 characters for docked prompts. For docked prompts, the maximum characters include HTML markup, not just readable text.
customApplication	Field Type string Description Internal use only. No data is populated for this field.
delayDays	Field Type int Description Required if recurrences are scheduled. Number of days in between occurrences. For a walkthrough, specify this value on the first step.
description	Field Type string Description Description. Maximum of 255 characters.
dismissButtonLabel	Field Type string Description Label for the dismiss button of a floating or targeted prompt. Maximum of 15 characters.
displayPosition	Field Type PromptDisplayPosition (enumeration of type string) Description The position of a floating prompt on the page. Valid values are: `BottomCenter` `BottomLeft` `BottomRight` `TopCenter` `TopLeft` `TopRight`
displayType	Field Type PromptDisplayType (enumeration of type string) Description Required. The type of prompt. Valid values are: `DockedComposer`—A docked prompt `FloatingPanel`—A floating prompt `Targeted`—A targeted prompt. Available in API version 52.0 and later.
elementRelativePosition	Field Type PromptElementRelativePosition (enumeration of type string) Description Indicates the location of a targeted 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	Field Type date Description The date to stop showing the in-app guidance. For a walkthrough, specify this value on the first step.
header	Field Type string Description Label for the header of a docked prompt. This value is the label contained in the window’s browser bar. Maximum of 36 characters.
image	Field Type string Description The developer name of the contentAsset that holds the image. You can specify this field or the `imageLink` field, but not both.
imageAltText	Field Type string Description Indicates the alt text of an image. Required if imageLocation, imageLink, or image is specified.
imageLink	Field Type string Description The URL for a prompt’s image. You can specify this field or the image field, but not both. Available in API version 53.0 and later.
imageLocation	Field Type picklist Description Indicates the location of the image in relation to the body text. Required if image, imageLink, or imageAltText is specified. Valid values are: `Top` `Bottom` `Right`, which is for floating or targeted prompts only `Left`, which is for floating or targeted prompts only
indexWithIsPublished	Field Type string Description Used by Salesforce for efficient querying.
indexWithoutIsPublished	Field Type string Description Used by Salesforce for efficient querying.
isPublished	Field Type boolean Description Indicates whether the in-app guidance is active (`true`) or not (`false`).
masterLabel	Field Type string Description Required. The label.
publishedByUser	Field Type string Description Internal use only. No data is populated for this field.
publishedDate	Field Type date Description Indicates the date the in-app guidance was activated. If installed from a package, this value is the date when the package was installed. For walkthroughs, this field can only be specified on the first step.
referenceElementContext	Field Type textarea Description Used by Salesforce to identify the element that the targeted prompt is associated with. Available in API version 52.0 and later.
shouldDisplayActionButton	Field Type boolean Description Indicates whether an action button or link is included (`true`) or not (`false`).
shouldIgnoreGlobalDelay	Field Type boolean Description Indicates whether 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	Field Type date Description Indicates the date to start showing the in-app guidance. For a walkthrough, specify this value on the first step. In API version 48.0 and earlier, this field is required.
stepNumber	Field Type int Description Required for walkthroughs only. Indicates the number of the last step the user viewed or interacted with in a walkthrough. Include up to 10 steps. Numbers must be consecutive without repeated or skipped numbers. Available in API version 49.0 and later.
targetAppDeveloperName	Field Type string Description The app’s developer name where the in-app guidance appears. Deprecated in API version 51.0 and later.
targetAppNamespacePrefix	Field Type string Description The app’s namespace prefix where the in-app guidance appears. This value 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	Field Type string Description Required. Used by Salesforce to identity the prompt’s page location along with targetPageKey2, targetPageKey3, targetPageKey4, and targetPageType.
targetPageKey2	Field Type string Description Used by Salesforce to identity the prompt’s page location along with targetPageKey1, targetPageKey3, targetPageKey4, and targetPageType.
targetPageKey3	Field Type string Description Used by Salesforce to identify the prompt’s page location along with targetPageKey1, targetPageKey2, targetPageKey4, and targetPageType.
targetPageKey4	Field Type string Description Used by Salesforce to identify the prompt’s page location along with targetPageKey1, targetPageKey2, targetPageKey3, and targetPageType. This field is available in API version 53.0 and later.
targetPageType	Field Type string Description Required. Used by Salesforce to identity the page location along with targetPageKey1, targetPageKey2, targetPageKey3, and targetPageKey4.
targetRecordType	Field Type string Description Used by Salesforce to determine if in-app guidance is specific to a record type. This field is available in API version 53.0 and later.
themeColor	Field Type PromptThemeColor (enumeration of type string) Description Indicates which custom theme color is applied to the in-app guidance. Required if themeSaturation is specified. For a walkthrough, specify this value on the first step. 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	Field Type PromptThemeSaturation (enumeration of type string) Description Indicates which color value, or saturation, is applied to the in-app guidance that has a custom theme color. Required if themeColor is specified. For a walkthrough, specify this value on the first step. Valid values are: `Dark` `Light`
timesToDisplay	Field Type int Description Required if recurrences are scheduled. The maximum number of times to show the in-app guidance. Salesforce detects whether the user interacts with the in-app guidance, then determines whether to show the in-app guidance again or cancel scheduled recurrences. Maximum value of 30. For a walkthrough, specify this value on the first step.
title	Field Type string Description Required. The label for the title. Maximum of 36 characters.
uiFormulaRule	Field Type UiFormulaRule[] Description 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	Field Type PromptUserAccess (enumeration of type string) Description 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	Field Type PromptUserProfileAccess (enumeration of type string) Description 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	Field Type int Description Required. The number remains `1` since multiple versions aren’t saved in the org.
videoLink	Field Type string Description The embed URL for a 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. See Considerations for Creating In-App Guidance.

UiFormulaRule

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

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

UiFormulaCriterion

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

Field Name	Description
leftValue	Field Type string Description Required. The field used for filtering. 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	Field Type string Description Required. Defines the operator used to filter the data. Valid value is `EQUAL`.
rightValue	Field Type string Description 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 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 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.