SfSkills Domains Docs GitHub

Home / admin / in-app-guidance-and-walkthroughs

in-app-guidance-and-walkthroughs

Configuring Salesforce In-App Guidance: floating, docked, and targeted prompts, multi-step walkthroughs, audience targeting, scheduling, and adoption analytics. Use when designing user onboarding or feature adoption programs in Lightning Experience. Covers the Prompt metadata type, promptVersions, displayType, uiFormulaRule, stepNumber, isPublished, PromptAction and PromptError. NOT for guidance on a record's Path — use admin/path-and-guidance. NOT for adoption and training — use admin/change-management-and-training.

Open the skill folder on GitHub

In-App Guidance and Walkthroughs

This skill activates when a practitioner needs to design, configure, or troubleshoot Salesforce In-App Guidance — the platform's native mechanism for delivering contextual prompts and multi-step walkthroughs to users directly inside Lightning Experience. It covers prompt type selection, walkthrough authoring, audience filtering, scheduling, limit management, and adoption analytics.

Before Starting

Gather this context before working on anything in this domain:

Questions to Ask Before Configuring

Ask these before opening Setup; the answers decide the metadata, and an LLM that skips them produces a prompt that deploys cleanly and reaches the wrong people at the wrong time.

AskWhy it mattersWhat a good answer adds
"Who exactly should see this — and is that group a profile?"Decides userAccess vs userProfileAccess, and whether a custom permission has to be built firstThe uiFormulaRule criteria list, plus the CustomPermission + PermissionSet files the gate needs
"What page does this sit on, and does anyone have a prompt on it already?"targetPageType / targetPageKey1 are required and opaque — they can only be harvested from a retrieve. Permission-based criteria work on app, Home, and record pages onlyThe sandbox prompt to build and retrieve, and confirmation the gate is even usable on that page
"Is it anchored to a specific element, or is it just a message?"A targeted prompt takes a maintenance dependency on the page layout; a floating one does notA displayType decision, and — if Targeted — the anchor recorded in description and added to the post-deploy PromptError check
"Should this go live on deploy, or later?"isPublished has no separate activation step; startDate is optional after API 49.0Either isPublished false plus a manual flip, or true plus a startDate on or after go-live
"How many times should one user see it, and how far apart?"There is no Once/Daily/Weekly enum — the Setup choices resolve to timesToDisplay (max 30) and delayDays (days, not seconds)Two integers instead of a frequency word, and the knowledge that engaged users stop seeing it early by design
"How will we know whether it worked, and who owns that read?"PromptAction is the only record of engagement, and its Times* fields are lifetime totals that survive a republishA named owner, a query filtered on LastDisplayDate, and a decision date to extend or retire
"What layout or Lightning-page changes are in flight for this page?"A layout deploy can silently degrade a targeted prompt on the same releaseThe anchor added to the release's dependency list

What a proper configuration adds over just building it in Setup: the audience is a permission you can grant and revoke rather than a profile you cannot narrow, the prompt goes live when the feature does rather than when the deploy lands, and a broken anchor is caught by a post-deploy query instead of by a user asking why a card is floating in the corner.

Core Concepts

One Metadata Type

Everything in this domain is the Prompt metadata type, stored at prompts/<Name>.prompt-meta.xml. A Prompt holds a masterLabel and a list of promptVersions. A single prompt is one promptVersions entry; a walkthrough is several, each with a stepNumber. There is no separate walkthrough type and no isWalkthrough flag. versionNumber is always 1.

Full deployable shapes are in references/metadata-examples.md.

Prompt Types

Three values of the required displayType field:

displayTypeWhat it isUse it for
FloatingPanelA repositionable card. displayPosition places it in one of six page corners/edges. Supports dismissButtonLabel.Org-wide announcements and explanatory steps that reference no specific element
DockedComposerAnchored to the bottom corner. Carries header (the label in the window's browser bar) and is the only type that takes videoLink.Feature demo video, richer content, lower workflow intrusion
TargetedAnchored to a UI element via referenceElementContext, positioned by elementRelativePosition. API 52.0+.Guiding a user to a precise field, button, or component

Targeted is the highest-signal type and the only one that takes a maintenance dependency on the page layout. referenceElementContext is written by Setup's targeting mode and has no documented hand-authoring syntax — targeted steps are built in the org and retrieved, not written from scratch.

Walkthroughs

A walkthrough is up to 10 steps, and step numbers must be consecutive with no repeats and no gaps. Salesforce's own adoption guidance recommends 5 or fewer; completion rates drop sharply beyond that.

Where a value goes matters, because a walkthrough's settings are not evenly distributed:

Walkthroughs count against the active walkthrough limit. A walkthrough is counted as active from the moment it is published, not when a user views it. Deactivating one frees the slot.

Audience

Two independent enums, both resolved through uiFormulaRule:

A uiFormulaRule holds a booleanFilter string and a list of criteria. Each criterion is a leftValue / operator / rightValue triple. operator accepts only EQUAL. leftValue accepts exactly three expression forms:

{!$Permission.CustomPermission.<name>}    rightValue: true    app, Home, record pages only
{!$Permission.StandardPermission.<name>}  rightValue: true    app, Home, record pages only
{!ENCODED:{!ID:$User.Profile.Key}}        rightValue: <profile name>   API 48.0+

If uiFormulaRule is null, the guidance displays to everyone by default. Because there is no negative operator, "everyone except X" has to be expressed as a positive gate on a second custom permission. See admin/custom-permissions for the permission design.

Scheduling

There is no Once / Daily / Weekly enum in the metadata. The Setup UI's frequency choices resolve to two integers plus a boolean:

"Once per user" is timesToDisplay of 1 with no delayDays.

Analytics

PromptAction is one row per user per prompt version and is the only record of engagement. It carries TimesDisplayed, TimesActionTaken, TimesDismissed, TimesSnoozed, LastDisplayDate, LastResultDate, StepNumber, StepCount, SnoozeUntil, and LastResult — whose values are CustomAction, Dismiss, Error, Finish (walkthroughs only), NoAction, NotSeen, and Snooze.

PromptError is the diagnostic companion, one row per failure, with Type in NoAccessToApp, NoAccessToPage, ReferenceElementNotFound, Unavailable. This is the table that tells you a targeted prompt's anchor is gone. Queries for both are in references/metadata-examples.md section 8.

Common Patterns

Pattern: Onboarding Walkthrough for a New Process

When to use: A new business process has been deployed — new fields, a new quick action, a changed approval flow — and you need users to understand the new steps without a live training session.

How it works:

  1. Build the custom permission and permission set for the cohort first, so the gate has something to resolve against.
  2. Open Setup > In-App Guidance and build the walkthrough against the live UI, using targeting mode for any anchored step.
  3. Keep it to 5 steps or fewer. Use Targeted for precise anchors and FloatingPanel for explanatory steps.
  4. Retrieve the prompt (sf project retrieve start --metadata Prompt:<Name>) — this is how you get real targetPageKey1 / targetPageType / referenceElementContext values into source control.
  5. Edit the retrieved file for the audience gate and schedule, run the checker, and deploy to the next environment.
  6. Verify as a cohort user, not as the admin — the admin will usually not hold the gating permission and is supposed to see nothing.

Why not just a floating announcement: A single prompt can announce a change but cannot guide a multi-step interaction. Sequential in-context instruction is what raises task completion.

Pattern: Feature Adoption Prompt with Video

When to use: You want to announce a new feature with a short demo video — common for Salesforce seasonal release updates or internal tooling launches.

How it works:

  1. Use displayType of DockedComposer — it is the only type that takes videoLink.
  2. Set videoLink to the embed URL, max 1,000 characters. Do not also set image; the two are mutually exclusive.
  3. Set header (max 36 chars) as well as title — docked prompts show both.
  4. Gate on the cohort and set a 30-day endDate so the announcement retires itself.
  5. Leave shouldIgnoreGlobalDelay false so the prompt does not compete with the initial page render.

Decision Guidance

SituationRecommended ApproachReason
Announcing an org-wide change to all usersFloatingPanel, uiFormulaRule omittedNull rule means it displays by default; no gate to maintain
Guiding users through a specific field or buttonTargeted, built in targeting mode and retrievedreferenceElementContext cannot be hand-authored
Delivering a feature demo videoDockedComposer with videoLinkOnly type that supports video; less intrusive than a modal
Multi-step process adoptionWalkthrough (up to 5 steps)Sequential guidance; higher completion than a single prompt
Audience is a pilot or project cohort, not a profileuserAccess = SpecificPermissions + custom permission criterionGrantable and revocable per user via a permission set
Audience is "everyone except group X"Positive gate on a second custom permissionoperator accepts only EQUAL; there is no negation
Page is not an app, Home, or record pageProfile criterion, or no gatePermission expressions are unsupported on other page types
Org already at the active walkthrough limitDeactivate a stale walkthrough (isPublished false) to free the slot, or use single-step promptsSingle prompts do not consume walkthrough slots
Prompt must not go live with the deployShip isPublished false, or true with a future startDateThere is no separate activation step after deploy
  1. Answer the Questions table above, then read references/gotchas.md — Gotcha 3 (audience is not profile-only) and Gotcha 8 (isPublished is live on arrival) change the design, not just the review.
  2. Build the audience gate first. Create the CustomPermission and the PermissionSet that enables it (shapes in references/metadata-examples.md section 5), and assign it to at least one test user who is not you.
  3. Build the prompt in a sandbox with Setup > In-App Guidance, then retrieve it — sf project retrieve start --metadata Prompt:<Name>. This is the only way to obtain valid targetPageType, targetPageKey1, and referenceElementContext values; the guide publishes no vocabulary for them.
  4. Edit the retrieved file against references/metadata-examples.md: add the uiFormulaRule, set timesToDisplay / delayDays / startDate / endDate, and decide isPublished. For a walkthrough, put schedule fields on step 1 and the action button on the last step, and renumber stepNumber consecutively from 1.
  5. Run the checker — python3 skills/admin/in-app-guidance-and-walkthroughs/scripts/check_in_app_guidance_and_walkthroughs.py --manifest-dir force-app/main/default. It fails the build on a published version with no targetPageType, an endDate before its startDate, step numbers that repeat or skip, and timesToDisplay above 30; it warns on ungated prompts, one-step walkthroughs, and field-length overruns.
  6. Deploy with --dry-run first, then for real, ordering CustomPermission → PermissionSet → Prompt in one manifest (references/metadata-examples.md sections 6–7).
  7. Verify as a gated user, then instrument. Confirm the prompt renders for a user holding the permission and not for one without it. Add the PromptError query to the post-deploy check for this page, and schedule the PromptAction read that decides whether to extend or retire the prompt.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems. Full detail, grounding, and the fix for each is in references/gotchas.md.

  1. A broken anchor degrades rather than disappears — a Targeted prompt whose element has moved converts to a floating prompt and logs PromptError.Type = ReferenceElementNotFound. No admin notification, so the query is the only signal.
  2. Slots are held by publication, not by usage — an inherited walkthrough nobody has opened in a year still occupies its slot until isPublished is set false.
  3. Profiles are the fallback gate, not the only one — SpecificPermissions plus a custom-permission criterion targets a cohort that no profile describes.
  4. versionNumber is not a step counter — it stays 1 on every entry; stepNumber is the one that increments, and it must be consecutive.
  5. delayDays is days, not seconds — it sets the gap between recurrences; shouldIgnoreGlobalDelay is the page-load control.
  6. A deploy with isPublished true is a go-live — there is no post-deploy activation step.
  7. Media fields are mutually exclusive, and imageAltText / imageLocation require each other.
  8. body length depends on the manifest's API version, not the org's — 240 chars for floating and targeted prompts before v60.0.
  9. Republishing resets display state, not analytics — the Times* counters are lifetime totals per user.
  10. AppExchange package prompts are exempt from org limits, though the Setup list shows them alongside org-created ones.

Output Artifacts

ArtifactDescription
prompts/<Name>.prompt-meta.xmlThe deployable Prompt, with promptVersions, uiFormulaRule, and schedule
customPermissions/ + permissionsets/ filesThe gate the uiFormulaRule resolves against, in the same manifest
package.xml entryPrompt, CustomPermission, PermissionSet types, deploy-ordered
PromptAction adoption reportViews, action clicks, dismissals, snoozes, and walkthrough drop-off step
PromptError post-deploy queryThe anchor audit; run after every layout or Lightning-page deploy
Targeted prompt anchor inventoryWhich UI element each targeted step depends on, for maintenance tracking

Reference Files

FileRead it when
references/metadata-examples.mdYou are writing or reviewing the actual XML: floating / docked / walkthrough shapes, the uiFormulaRule gate, the custom permission and permission set, package.xml, retrieve and deploy commands, and the PromptAction / PromptError verification SOQL
references/gotchas.mdSomething is not rendering, a deploy failed, or you are about to trust a field name that reads like it means something else — 10 grounded platform behaviours with guide line citations
references/examples.mdYou want a worked scenario end to end: the walkthrough, the video prompt, and the recurring-acknowledgement pattern, with the anti-pattern that produces an 8-step walkthrough
references/well-architected.mdYou are justifying the design in a review — pillar mapping, the targeted-vs-floating and free-tier-vs-licence tradeoffs, and the official sources this skill rests on
references/llm-anti-patterns.mdYou are reviewing AI-generated in-app guidance advice or configuration and need the specific failure modes to check for

Package files