10.2 User Assistance: ToolTips, Teaching Tips & In-App Tours

10.2 User Assistance: ToolTips, Teaching Tips & In-App Tours

In modern cloud enterprise resource planning (ERP) systems, self-service discoverability and in-context user assistance are critical to driving user adoption and reducing support costs. Users expect business software that guides them intuitively through complex workflows without requiring dense PDF user manuals or formal classroom training. In Microsoft Dynamics 365 Business Central, developers implement user assistance using a structured, four-tier framework: ToolTips, Teaching Tips (AboutTitle / AboutText), In-App Tours, and Context-Sensitive Help Links.

1. The Four-Tier User Assistance Architecture

Microsoft defines a structured four-tier user assistance model in Business Central designed to deliver the right depth of assistance at the exact moment of user need:

┌─────────────────────────────────────────────────────────────┐
│ Tier 4: External Conceptual Help (Learn / HelpBaseUrl)     │
│   ▲                                                         │
│ Tier 3: Guided In-App Tours (Chained Multi-Step Walkthrough)│
│   ▲                                                         │
│ Tier 2: In-Context Feature Callouts (Teaching Tips)         │
│   ▲                                                         │
│ Tier 1: Micro-Guidance (Actionable ToolTips on all controls)│
└─────────────────────────────────────────────────────────────┘

1. Tier 1: Micro-Guidance (ToolTips): Brief, instantaneous explanations displayed when a user hovers over or focuses on a field caption, action button, or cue tile.
2. Tier 2: In-Context Feature Highlights (Teaching Tips): Rich callout bubbles anchored to pages or specific controls that explain the business purpose of a feature and provide quick onboarding tips.
3. Tier 3: Guided Workflows (In-App Tours): Sequential step-by-step walkthroughs that chain multiple teaching tips across a page to guide first-time users through complex business tasks.
4. Tier 4: Deep Conceptual Learning (External Documentation): Embedded hyperlinks (AboutUrl and ContextSensitiveHelpPage) that direct users to comprehensive documentation articles on Microsoft Learn or ISV help portals.

2. Actionable ToolTips (ToolTip Property)

Every field, action, part, and cue on a Business Central page should define a meaningful ToolTip property. For AppSource marketplace validation, omitting tooltips on user-interactive controls raises the CodeCop diagnostics AA0218 (You must write a tooltip in the Tooltip property for all controls of type Action and Field that exist on page objects) and AA0220 (The value of the Tooltip property of Fields must be filled), and leads to AppSource submission rejections.

Microsoft ToolTip Phrasing Guidelines

To ensure consistency across the entire application ecosystem, Microsoft enforces strict stylistic rules for writing tooltips:

• Action-Oriented Verbs: Start field tooltips with active verbs such as "Specifies...", "Shows...", or "Indicates...". Start action tooltips with imperative action verbs such as "Calculate...", "Post...", "Open...", or "Export...".
• Explain Downstream Impact / Business Why: Do not merely restate the control's caption. Explain what the value is used for, how it impacts subsequent accounting or posting routines, or where it originates.
• Avoid Technical Jargon: Do not reference internal database field names, C/AL / AL data types, table numbers, or SQL terminology.
• Conciseness & Formatting: Limit tooltips to 1–2 clear, grammatically complete sentences. End with a period.

Comparison: Ineffective vs. Effective ToolTips

AL Code Example: Applying ToolTips to Fields and Actions

page 50125 "Loyalty Journal"
{
    PageType = Worksheet;
    SourceTable = "Loyalty Journal Line";
    UsageCategory = Tasks;
    ApplicationArea = All;

    layout
    {
        area(Content)
        {
            repeater(Group)
            {
                field("Member No."; Rec."Member No.")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the loyalty member account number to which points will be credited or debited.';
                }
                field("Points Adjusted"; Rec."Points Adjusted")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the number of points to add (positive value) or deduct (negative value) from the member balance.';
                }
            }
        }
    }

    actions
    {
        area(Processing)
        {
            action(PostJournal)
            {
                Caption = 'Post';
                Image = PostOrder;
                ApplicationArea = All;
                ToolTip = 'Finalizes the journal entries and updates member point balances in the loyalty ledger.';

                trigger OnAction()
                begin
                    Codeunit.Run(Codeunit::"Loyalty Journal-Post", Rec);
                end;
            }
        }
    }
}

3. Teaching Tips (AboutTitle, AboutText, AboutUrl)

Teaching Tips are in-context callout dialogs that teach users how to use a page or a specific high-value feature. They appear when the user first opens a page (proactive onboarding) or when the user clicks the page title or feature info icon.

Teaching Tip Properties

Teaching tips are declared directly in AL using three dedicated properties:

• AboutTitle: A short, engaging headline (Microsoft's onboarding guidance recommends keeping it to a few words) summarizing the page or control purpose (e.g., 'About Loyalty Management' or 'Managing Point Redemptions').
• AboutText: A concise explanation (up to several sentences) describing what the feature does, key benefits, and recommended operational steps.
• AboutUrl: An optional absolute URL pointing to external rich documentation, a Microsoft Learn module, or video tutorial.

Page-Level vs. Control-Level Teaching Tips

1. Page-Level Teaching Tip: Declared at the root page level. It introduces the overall business concept of the page when the page is opened.
2. Control-Level Teaching Tip: Declared on specific groups, fields, FastTabs, or actions. It highlights advanced or non-obvious functionality.

page 50130 "Customer Reward Card"
{
    PageType = Card;
    SourceTable = "Customer";
    Caption = 'Customer Reward Profile';
    
    // Page-Level Teaching Tip (Step 1 of Tour)
    AboutTitle = 'About Customer Rewards';
    AboutText = 'This page allows you to view accumulated loyalty points, assign reward tiers, and configure special customer promotional discounts.';
    AboutUrl = 'https://learn.microsoft.com/dynamics365/business-central/';

    layout
    {
        area(Content)
        {
            group(General)
            {
                Caption = 'General';
                
                field("No."; Rec."No.")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the unique customer identification number.';
                }
                field(Name; Rec.Name)
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the customer legal name used on all sales documents.';
                }
            }
            group(Rewards)
            {
                Caption = 'Loyalty Rewards';
                
                // Control-Level Teaching Tip (Step 2 of Tour)
                field("Reward Tier Code"; Rec."Reward Tier Code")
                {
                    ApplicationArea = All;
                    ToolTip = 'Specifies the loyalty tier assigned to this customer.';
                    AboutTitle = 'Configuring Reward Tiers';
                    AboutText = 'Assigning a tier automatically applies eligible line discounts on sales orders for this customer.';
                }
                field("Reward Points"; Rec."Reward Points")
                {
                    ApplicationArea = All;
                    ToolTip = 'Shows the total unredeemed reward points currently available.';
                }
            }
        }
    }

    actions
    {
        area(Processing)
        {
            // Action-Level Teaching Tip (Step 3 of Tour)
            action(AdjustPoints)
            {
                Caption = 'Adjust Points';
                Image = AdjustQuantity;
                ApplicationArea = All;
                ToolTip = 'Opens the point adjustment dialog to manually credit or debit points.';
                AboutTitle = 'Manual Point Adjustments';
                AboutText = 'Use this action to award promotional bonus points or correct discrepancy claims for the customer.';

                trigger OnAction()
                begin
                    Message('Opening point adjustment dialog...');
                end;
            }
        }
    }
}

4. In-App Tours & Context-Sensitive Help Configuration

When developers define both page-level and control-level teaching tips on a page, Business Central automatically binds them together into an interactive In-App Tour.

In-App Tour Lifecycle and User Experience

1. First-Time Discovery: When a user opens the page for the first time, the page-level teaching tip bubble appears automatically.
2. Tour Navigation: The teaching tip dialog displays a "Take a tour" or "Next" button. Clicking next advances the callout bubble to the next control or action that defines an AboutTitle and AboutText.
3. Spotlight Effect: While the tour is active, the Web Client dims the surrounding background and highlights (spotlights) the active control.
4. Dismissal & Recall: Users can dismiss the tour at any time by clicking "Got it". If they want to revisit the tour later, they can click the page title in the top-left banner or open the Help & Support pane and choose "Restart Tour".

Context-Sensitive Help (ContextSensitiveHelpPage & app.json)

Beyond teaching tips, Business Central provides deep contextual help links that open targeted documentation when users press Ctrl+F1 or choose Help:

1. In app.json Manifest: Define the base URL where your extension's help articles are hosted and the supported language locales:

   {
     "helpBaseUrl": "https://docs.myisvsolution.com/{0}/",
     "supportedLocales": ["en-US", "da-DK", "de-DE"]
   }
   

2. In AL Page Objects: Specify the relative article path using ContextSensitiveHelpPage:

   page 50130 "Customer Reward Card"
   {
       ContextSensitiveHelpPage = 'loyalty/managing-customer-rewards';
       // When user opens Help, BC navigates to https://docs.myisvsolution.com/en-US/loyalty/managing-customer-rewards
   }