v1.0.0 to v1.1.0
160 added, 75 removed. Audit A to A.
---
name: in-app-guidance-and-walkthroughs
- description: "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. NOT for guidance on a record's Path — use admin/path-and-guidance. NOT for adoption and training — use admin/change-management-and-training."
+ description: "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."
category: admin
salesforce-version: "Spring '25+"
well-architected-pillars:
- Operational Excellence
triggers:
- "how do I create a walkthrough to guide users through a new process in Salesforce"
- "set up in-app prompts to help users adopt a feature without a training session"
- "targeted prompt is not showing up for users on the opportunity page"
- "what is the limit on custom walkthroughs before needing a Sales Enablement license"
- "configure audience filtering for in-app guidance by profile"
+ - "deploy a Prompt metadata file with sf project deploy start"
+ - "targeted prompt turned into a floating prompt after a page layout change"
+ - "restrict an in-app prompt to users with a custom permission using uiFormulaRule"
+ - "walkthrough step numbers must be consecutive without repeated or skipped numbers"
+ - "query PromptAction to report on prompt views dismissals and walkthrough completions"
+ - "prompt went live the moment I deployed it isPublished"
tags:
- in-app-guidance
- walkthroughs
- prompts
- user-adoption
- onboarding
- lightning-experience
inputs:
- Target Lightning Experience page and UI element anchor (for targeted prompts)
- - User profiles to include in audience targeting
- - Walkthrough step content and action type (float, dock, target)
- - Scheduling window (start date, end date, display frequency)
+ - Audience definition — the custom permission, permission set, or profiles that scope it
+ - Walkthrough step content and display type (FloatingPanel, DockedComposer, Targeted)
+ - Scheduling window (startDate, endDate, timesToDisplay, delayDays)
- Whether Sales Enablement license is provisioned
outputs:
- - Configured prompt or walkthrough in the In-App Guidance builder
- - Audience-filtered scheduling rules for each prompt
- - Adoption tracking queries against the PromptAction standard object
+ - Deployable `prompts/<Name>.prompt-meta.xml` and its package.xml entry
+ - The custom permission and permission set that the uiFormulaRule gate resolves against
+ - Adoption tracking queries against the PromptAction and PromptError standard objects
- Recommendations on prompt type selection and step count
dependencies: []
- version: 1.0.0
+ version: 1.1.0
author: Pranav Nagrecha
- updated: 2026-04-05
+ updated: 2026-09-04
---
# 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:
- - Confirm the org is on Lightning Experience. In-App Guidance does not function in Salesforce Classic or Experience Cloud (Guest/Partner portals require PRM licenses and use a different engine).
- - Identify how many active custom walkthroughs the org already has. The free tier allows exactly 3 active walkthroughs. Exceeding that limit requires a Sales Enablement license (~$25/user/month as of Spring '25). Prompts created by AppExchange managed packages do not count against this cap.
- - Determine which user profiles should see each prompt. Audience targeting is profile-based only as of Spring '25 — permission sets, roles, territories, and behavioral signals are not supported natively.
- - Identify the anchor element for any targeted prompt. If the anchor UI element is removed or renamed in a future release or layout change, the targeted prompt will silently stop appearing with no error surfaced to admins.
+ - **Confirm the rendering surface.** In-App Guidance does not function in Salesforce Classic. It *does* work in supported Experience Cloud site pages — both the Metadata API guide and the Object Reference say so — so a partner-portal rollout is not automatically ruled out. See `references/gotchas.md` Gotcha 5 for the exact wording and what remains unverified.
+ - **Identify how many active custom walkthroughs the org already has.** The free tier is documented as 3 active walkthroughs, with more requiring a Sales Enablement license; prompts installed by AppExchange managed packages are exempt. UNVERIFIED (2026-09-04): both the 3-slot figure and the licence requirement rest on the Salesforce Help "Limits for In-App Guidance" article, which cannot be fetched; the v62 Metadata API guide and the App Limits cheat sheet state no such cap. Count the org's own active prompts before planning around it.
+ - **Decide the audience gate.** Targeting is *not* profile-only. `userAccess` = `SpecificPermissions` plus a `uiFormulaRule` on `{!$Permission.CustomPermission.<name>}` targets an arbitrary cohort; the profile expression is the fallback, not the only option.
+ - **Identify the anchor element for any targeted prompt.** If the anchor is removed or moved, the targeted prompt does not disappear — it degrades into a floating prompt and writes a `PromptError` row of type `ReferenceElementNotFound`. Nothing notifies the admin, so the query has to be run.
+ - **Decide the activation model before the deploy.** `isPublished` is a plain metadata field. Deploying `true` makes the prompt live on arrival.
+ ## 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.
+
+ | Ask | Why it matters | What 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 first | The `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 only | The 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 not | A `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.0 | Either `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 republish | A 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 release | The 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
- ### Prompt Types
+ ### One Metadata Type
- Salesforce provides three prompt types, each with distinct behaviors and trade-offs:
+ 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`.
- **Floating prompts** are repositionable modal-style cards. The user can drag them to a different position on the page. They are the most flexible prompt type and work anywhere in Lightning Experience. Use them for org-wide announcements or general onboarding messages that do not need to point at a specific UI element.
+ Full deployable shapes are in `references/metadata-examples.md`.
- **Docked prompts** appear anchored to the bottom corner of the screen. They support embedded video (YouTube or a direct video URL) and are designed for richer content such as feature overview clips. Because they stay docked rather than overlaying content, they have lower intrusion on user workflow. Use them when video is the primary communication medium.
+ ### Prompt Types
- **Targeted prompts** are anchored to a specific UI element on the page — a button, field, list, or other component. They draw a visual indicator from the element to the prompt body. They are the highest-signal type for guiding users through precise UI interactions. The critical constraint: if the anchor element is removed, renamed, or moved to a different page layout, the prompt silently stops rendering. There is no admin alert.
+ Three values of the required `displayType` field:
+ | `displayType` | What it is | Use it for |
+ |---|---|---|
+ | `FloatingPanel` | A 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 |
+ | `DockedComposer` | Anchored 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 |
+ | `Targeted` | Anchored 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 a sequence of up to 10 individual prompt steps delivered in order. Each step uses one of the three prompt types. Salesforce's own guidance recommends keeping walkthroughs to 5 steps or fewer; completion rates drop sharply beyond that threshold.
+ 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.
- Walkthroughs count against the active walkthrough limit (3 on the free tier). A walkthrough is counted as active from the moment it is published and scheduled, not when a user views it. Deactivating a walkthrough frees the slot.
+ Where a value goes matters, because a walkthrough's settings are not evenly distributed:
- ### Audience and Scheduling
+ - **First step:** `startDate`, `endDate`, `delayDays`, `timesToDisplay`, `publishedDate`, `themeColor`, `themeSaturation`
+ - **Last step:** `actionButtonLabel`, `actionButtonLink`
+ - **Every step:** `body`, `masterLabel`, `title`, `displayType`, `versionNumber`, `targetPageType`, `targetPageKey1`
- Audience targeting is configured per prompt or walkthrough using profiles. You can include one or more profiles. As of Spring '25, there is no native support for role-based, territory-based, or behavioral targeting (e.g., "show only to users who have not completed this step").
+ 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.
- Scheduling controls define:
- - **Start date / End date**: the window in which the prompt is eligible to appear
- - **Display frequency**: how often a user sees the prompt (every session, once, daily, weekly)
- - **Page-load delay**: optional delay in seconds before the prompt renders after page load
+ ### Audience
+ Two independent enums, both resolved through `uiFormulaRule`:
+
+ - `userProfileAccess` — `Everyone` or `SpecificProfiles` (API 48.0+)
+ - `userAccess` — `Everyone` or `SpecificPermissions`
+
+ 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:
+
+ ```text
+ {!$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:
+
+ - `startDate` / `endDate` — the eligibility window. `startDate` is optional in API 49.0+ and required in 48.0 and earlier.
+ - `timesToDisplay` — maximum showings per user, capped at 30. Salesforce cancels remaining recurrences once the user interacts, so "up to 3" often means one.
+ - `delayDays` — **days between occurrences**, not seconds before render.
+ - `shouldIgnoreGlobalDelay` — `true` skips the org's global time delay and shows on page load.
+
+ "Once per user" is `timesToDisplay` of 1 with no `delayDays`.
+
### Analytics
- Prompt interaction data is written to the `PromptAction` standard object. Each record captures whether a user dismissed or completed a prompt step, along with timestamps and profile information. You can build reports and dashboards directly on `PromptAction`. Salesforce Labs publishes an AppExchange report pack with pre-built dashboards for adoption tracking.
+ `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. Open Setup > In-App Guidance.
- 2. Click "Add" and select "Walkthrough."
- 3. Navigate to the starting page in Lightning Experience. The builder overlays the live UI.
- 4. Add a floating or targeted step pointing at the first new element. Write concise action-oriented step copy ("Click the new Approval Status field to open the picklist").
- 5. Add subsequent steps (keep to 5 or fewer). Use targeted prompts for precise UI anchors; use floating prompts for explanatory steps that do not reference a specific element.
- 6. Set audience to the relevant profile(s). Set a start date. Set display frequency to "Once" to avoid re-showing after a user completes the walkthrough.
- 7. Activate.
+ 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 use a floating announcement:** A floating single prompt can announce a change but cannot guide users through multi-step interactions. A walkthrough provides sequential in-context instruction that improves task completion rates.
+ **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. Create a docked prompt (not a walkthrough — a single docked step is sufficient for video delivery).
- 2. Paste the video URL in the docked prompt content editor.
- 3. Set audience to relevant profiles.
- 4. Set display frequency to "Once per user."
- 5. Set a short page-load delay (2–3 seconds) so the prompt appears after the user's primary page content has loaded.
+ 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
| Situation | Recommended Approach | Reason |
|---|---|---|
- | Announcing an org-wide change to all users | Floating prompt, no audience filter | Maximum reach, no profile restriction needed |
- | Guiding users through a specific field or button | Targeted prompt | Visual anchor draws attention to the exact element |
- | Delivering a feature demo video | Docked prompt | Native video support; less intrusive than a modal |
+ | Announcing an org-wide change to all users | `FloatingPanel`, `uiFormulaRule` omitted | Null rule means it displays by default; no gate to maintain |
+ | Guiding users through a specific field or button | `Targeted`, built in targeting mode and retrieved | `referenceElementContext` cannot be hand-authored |
+ | Delivering a feature demo video | `DockedComposer` with `videoLink` | Only type that supports video; less intrusive than a modal |
| Multi-step process adoption | Walkthrough (up to 5 steps) | Sequential guidance; higher completion than a single prompt |
- | Org already has 3 active walkthroughs, budget is constrained | Deactivate an older walkthrough to free the slot, or use single-step prompts (no walkthrough limit) | Walkthroughs consume the 3-slot free-tier cap; single prompts do not |
- | Audience segment not expressible by profile | Consider custom onboarding via Flow + platform events, or evaluate Sales Enablement license features | Native in-app guidance does not support role, territory, or behavioral audience filters |
+ | Audience is a pilot or project cohort, not a profile | `userAccess` = `SpecificPermissions` + custom permission criterion | Grantable and revocable per user via a permission set |
+ | Audience is "everyone except group X" | Positive gate on a second custom permission | `operator` accepts only `EQUAL`; there is no negation |
+ | Page is not an app, Home, or record page | Profile criterion, or no gate | Permission expressions are unsupported on other page types |
+ | Org already at the active walkthrough limit | Deactivate a stale walkthrough (`isPublished` false) to free the slot, or use single-step prompts | Single prompts do not consume walkthrough slots |
+ | Prompt must not go live with the deploy | Ship `isPublished` false, or true with a future `startDate` | There is no separate activation step after deploy |
---
## Recommended Workflow
- Step-by-step instructions for an AI agent or practitioner working on this task:
-
- 1. Confirm the target environment is Lightning Experience and identify the org's current active walkthrough count against the 3-slot free tier limit.
- 2. Clarify prompt type: floating (repositionable, general), docked (video-friendly, bottom-pinned), or targeted (anchored to a specific UI element). Match the type to the communication goal.
- 3. If building a walkthrough, plan step count first — do not exceed 5 steps. Map each step to a specific Lightning Experience page and, for targeted steps, identify the precise UI element anchor.
- 4. Configure audience targeting by profile. Confirm which profiles the intended users belong to. Note that roles, territories, and permission sets are not valid audience criteria.
- 5. Set scheduling: start date, optional end date, display frequency (once is standard for process walkthroughs; daily or weekly for ongoing nudges), and optional page-load delay.
- 6. Activate and verify in the target page under a test user with the correct profile. Confirm the prompt renders, anchors correctly (for targeted), and the scheduling rules fire.
- 7. After 2–4 weeks, query the `PromptAction` object to measure completion rates. Use the Salesforce Labs AppExchange report pack or build custom reports. Use completion data to decide whether to deactivate, revise, or extend the prompt.
+ 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:
- - [ ] Active walkthrough count confirmed — org is within the 3-slot free tier or Sales Enablement license is provisioned
- - [ ] Prompt type selected matches communication goal (floating / docked / targeted)
- - [ ] Walkthrough step count is 5 or fewer
- - [ ] Audience profiles are correct — roles and territories are not used as audience criteria
- - [ ] Targeted prompt anchors verified to exist on current page layouts in Lightning Experience
- - [ ] Scheduling window, frequency, and optional delay are configured
- - [ ] Prompt tested under a user with the correct profile in Lightning Experience
- - [ ] PromptAction reporting approach identified for post-launch adoption measurement
+ - [ ] Active walkthrough count confirmed against the org's own limit before publishing a new one
+ - [ ] `displayType` matches the communication goal (`FloatingPanel` / `DockedComposer` / `Targeted`)
+ - [ ] Walkthrough step count is 5 or fewer, and `stepNumber` runs 1..n with no repeats or gaps
+ - [ ] `versionNumber` is `1` on every `promptVersions` entry
+ - [ ] Audience gate is deliberate — a custom permission where the cohort is not a profile, and the permission set is in the same deployment
+ - [ ] `targetPageType` / `targetPageKey1` came from a retrieve, not from a guess
+ - [ ] Targeted prompts have the anchor element recorded in `description`
+ - [ ] Schedule reviewed as metadata: `timesToDisplay` (≤30), `delayDays` in days, `startDate` / `endDate` on step 1
+ - [ ] `isPublished` matches the intended go-live, and a `startDate` backs it up if the deploy lands early
+ - [ ] Media fields are singular — `videoLink` **or** `image`/`imageLink`, with `imageAltText` and `imageLocation` if any image element is present
+ - [ ] Checker run clean against the manifest directory
+ - [ ] Tested under a user who holds the gating permission, and under one who does not
+ - [ ] `PromptError` query added to the post-deploy check for the affected page
+ - [ ] `PromptAction` reporting approach and owner identified for post-launch adoption measurement
---
## Salesforce-Specific Gotchas
- Non-obvious platform behaviors that cause real production problems:
+ Non-obvious platform behaviors that cause real production problems. Full detail, grounding, and the fix for each is in `references/gotchas.md`.
- 1. **Silent targeted prompt failure on anchor removal** — If the UI element a targeted prompt is anchored to is removed from the page layout, the targeted prompt stops rendering entirely with no error or admin notification. This is the most common support ticket for in-app guidance. Always document the anchor element in a prompt description field and audit targeted prompts after any layout change.
+ 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.
- 2. **Walkthrough slot counted on activation, not on user view** — A walkthrough consumes one of the 3 free-tier slots as soon as it is published and active, regardless of whether any user has seen it. An org with 3 active but rarely-used walkthroughs from a prior project will block new walkthrough creation. Always audit the Manage Prompts page and deactivate stale walkthroughs.
+ ---
- 3. **Audience filtering is profile-only** — A common misreading of the documentation leads admins to expect role-based or permission-set-based targeting. As of Spring '25 only profiles are supported. If the intended audience does not map cleanly to a single profile, you either accept over-delivery or implement a custom solution (e.g., Flow-driven contextual messaging).
+ ## Output Artifacts
- 4. **AppExchange package prompts are exempt from org limits** — Prompts installed via managed AppExchange packages do not count against the 3 active walkthrough cap. This distinction is not obvious in the Manage Prompts UI, which shows these prompts alongside org-created ones.
+ | Artifact | Description |
+ |---|---|
+ | `prompts/<Name>.prompt-meta.xml` | The deployable `Prompt`, with `promptVersions`, `uiFormulaRule`, and schedule |
+ | `customPermissions/` + `permissionsets/` files | The gate the `uiFormulaRule` resolves against, in the same manifest |
+ | `package.xml` entry | `Prompt`, `CustomPermission`, `PermissionSet` types, deploy-ordered |
+ | PromptAction adoption report | Views, action clicks, dismissals, snoozes, and walkthrough drop-off step |
+ | PromptError post-deploy query | The anchor audit; run after every layout or Lightning-page deploy |
+ | Targeted prompt anchor inventory | Which UI element each targeted step depends on, for maintenance tracking |
---
- ## Output Artifacts
+ ## Reference Files
- | Artifact | Description |
+ | File | Read it when |
|---|---|
- | Configured In-App Guidance prompt or walkthrough | Live in the org's Manage Prompts page, ready to activate or scheduled |
- | Audience and scheduling configuration | Profile filters, start/end dates, frequency, and delay settings attached to the prompt |
- | PromptAction adoption report | Custom or AppExchange report tracking user completion, dismissal, and engagement rates |
- | Targeted prompt anchor inventory | Documentation of which UI elements each targeted prompt depends on for maintenance tracking |
+ | `references/metadata-examples.md` | You 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.md` | Something 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.md` | You 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.md` | You 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.md` | You are reviewing AI-generated in-app guidance advice or configuration and need the specific failure modes to check for |
---
## Related Skills
- - change-management-and-training — Use when in-app guidance is one component of a broader change program requiring stakeholder communication, training materials, and rollout planning
- - experience-cloud-security — Experience Cloud sites cannot use Lightning Experience In-App Guidance; consult this skill when guidance needs extend to partner or customer portals
+ - `admin/change-management-and-training` — decides *which* guidance to build, for whom, and alongside what other communication; this skill builds what that one specified
+ - `admin/custom-permissions` — the audience gate: naming, dependency chains, and permission-set assignment for the custom permission a `uiFormulaRule` targets
+ - `admin/dynamic-forms-and-actions` — the layout changes most likely to move or remove a targeted prompt's anchor element
+ - `admin/app-and-tab-configuration` — app and Home page context for `targetPageType`, and the app-access errors behind `PromptError.Type = NoAccessToApp`
+ - `admin/path-and-guidance` — Path's Guidance for Success is the record-stage-bound alternative to a prompt; use it when the guidance belongs to a stage rather than to a rollout
+ - `security/experience-cloud-security` — read before extending guidance to a partner or customer site, where supported-page coverage and site permissions both apply