Prompt (Beta) | Metadata API Developer Guide

As a beta feature, Prompts is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature.

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. For non-admin users, assign the Manage Prompts and Modify Metadata user permission. Everyone can see the In-App Guidance setup page.

Packaging Prompts

See Creating Managed Packages in Salesforce Help for more information.

To create a managed package in a Developer edition org, set an org namespace prefix first. You aren’t able to create a prompt without one.

Unmanaged packages for prompts isn’t supported.

When orgs install prompts from packages, the prompts are inactive until the admin activates them.

Fields

Field Name	Field Type	Description
masterLabel	string	Required. The master label for the prompt. Maximum of 80 characters.
promptVersions	PromptVersion	A list of prompt entries. Each entry represent a different prompt.

PromptVersion

A list of prompt entries. Each entry represents a different prompt.

Field Name	Field Type	Description
actionButtonLabel	string	Label for the action button. Maximum of 25 characters.
actionButtonLink	string	URL for the action button. Maximum of 255 characters.
body	string	Required. Body content of the prompt. For floating prompts, there’s a maximum of 120 characters. For docked prompts, there’s a maximum of 4000 characters.
delayDays	int	Required if recurrences are scheduled. Number of days in between occurrences of the prompt.
description	string	Description of the prompt. Maximum of 255 characters.
dismissButtonLabel	string	Label for the dismiss button. 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
endDate	date	Indicates the date to stop showing the prompt.
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.
indexWithIsPublished	string	Used by Salesforce for efficient querying.
indexWithoutIsPublished	string	Used by Salesforce for efficient querying.
isPublished	boolean	Indicates if a prompt is active `true` or not `false`.
masterLabel	string	Required. The master label for the prompt.
publishedByUser	string	The ID of the user who activated the prompt.
publishedDate	date	Indicates the date the prompt was activated.
shouldDisplayActionButton	boolean	Required. Indicates if an action button is included in the prompt `true` or not `false`.
startDate	date	Required. Indicates the date to start showing the prompt.
targetAppDeveloperName	string	Required. The app’s developer name where the prompt appears.
targetAppNamespacePrefix	string	The app’s namespace prefix where the prompt appears.
targetPageKey1	string	Required. Used by Salesforce to identity the prompt page location along with `targetPageKey2` and `targetPageType`.
targetPageKey2	string	Required. Used by Salesforce to identity the prompt page location along with `targetPageKey1` and `targetPageType`.
targetPageType	string	Required. Used by Salesforce to identity the prompt page location along with `targetPageKey1` and `targetPageKey2`.
timesToDisplay	int	Required if recurrences are scheduled. Maximum number of times to display the prompt (that is, the number of occurrences). Salesforce detects if the user interacts with (or ignores) the prompt to determine if we should show the prompt again or cancel scheduled recurrences. This might run counter to the number of occurrences scheduled. Maximum value of 30.
title	string	Required. The label for the title of the prompt. Maximum of 36 characters.
uiFormulaRule	UiFormulaRule	A set of one or more permission filters that define the conditions under which the prompt displays on the page. If the rule evaluates to `true`, the prompt displays on the page. If `false`, it doesn't display. If this field is `null`, the prompt displays by default.
userAccess	PromptUserAccess (enumeration of type string)	Required. Indicates who can see the prompt. Valid values are: `Everyone`, which indicates that there’s no restrictions on who can see the prompt `SpecificPermissions`, which indicates that only users with all the specific user permissions specified can see the prompt Users must have the View Setup and Configuration permission to see prompts only visible with specific permissions. They can see prompts visible to everyone without this user permission.
versionNumber	int	Required. The number remains `1` since multiple versions aren’t saved in the org.

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 prompt visibility.

UiFormulaCriterion

A single filter that, when evaluated, helps define prompt 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 prompt visibility. `{!$Permission.CustomPermission.permissionName}`—Use this expression to control prompt 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 prompt visibility based on the standard permissions of the user viewing the Lightning page. Supported for app, Home, and record pages only.
operator	string	Required. Defines the operator used to filter the data. Valid value is `EQUAL`.
rightValue	boolean	Specifies if you want to evaluate the prompt’s visibility. Use `true`.

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        <publishedByUserName>mar3Test mar3User</publishedByUserName>
17        <publishedDate>2019-03-11</publishedDate>
18        <shouldDisplayActionButton>false</shouldDisplayActionButton>
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        <versionNumber>1</versionNumber>
26        <uiFormulaRule>
27            <booleanFilter>1 AND 2 AND 3 AND 4 AND 5 AND 6 AND 7</booleanFilter>
28            <criteria>
29                <leftValue>{!$Permission.StandardPermission.ActivitiesAccess}</leftValue>
30                <operator>EQUAL</operator>
31                <rightValue>TRUE</rightValue>
32            </criteria>
33            <criteria>
34                <leftValue>{!$Permission.StandardPermission.ContentWorkspaces}</leftValue>
35                <operator>EQUAL</operator>
36                <rightValue>TRUE</rightValue>
37            </criteria>
38            <criteria>
39                <leftValue>{!$Permission.StandardPermission.AllowViewKnowledge}</leftValue>
40                <operator>EQUAL</operator>
41                <rightValue>TRUE</rightValue>
42            </criteria>
43            <criteria>
44                <leftValue>{!$Permission.StandardPermission.AuthorApex}</leftValue>
45                <operator>EQUAL</operator>
46                <rightValue>TRUE</rightValue>
47            </criteria>
48            <criteria>
49                <leftValue>{!$Permission.StandardPermission.EditEvent}</leftValue>
50                <operator>EQUAL</operator>
51                <rightValue>TRUE</rightValue>
52            </criteria>
53            <criteria>
54                <leftValue>{!$Permission.StandardPermission.LightningExperienceUser}</leftValue>
55                <operator>EQUAL</operator>
56                <rightValue>TRUE</rightValue>
57            </criteria>
58            <criteria>
59                <leftValue>{!$Permission.CustomPermission.MyCustomPerm}</leftValue>
60                <operator>EQUAL</operator>
61                <rightValue>TRUE</rightValue>
62            </criteria>
63        </uiFormulaRule>
64    </promptVersions>
65</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.