Study guide

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

Microsoft Dynamics 365 Business Central Developer MB-820

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Business Central Architecture & Platform Foundation

1.1 Business Central Architecture & Extensions Model 1.2 Customization Lifecycle: Cloud (SaaS) vs. On-Premises 1.3 Base Application, System Application & AppSource

2 Chapter 2: Development Environment & Configuration

2.1: Development Environment Setup: VS Code, AL: Go! Projects & Sandboxes 2.2: AL Configuration Files: app.json & launch.json Parameters 2.3: Multi-Root Workspaces & Project Dependencies

3 Chapter 3: Extension Lifecycle: Debugging, Deployment, Multilanguage & Maintenance

3.1 Debugging & Snapshot Debugging in Visual Studio Code 3.2 Extension Deployment & Schema Synchronization Modes 3.3 Multilanguage Development with XLIFF & Translation Files 3.4 Extension Maintenance, Deprecation & Breaking Changes

4 Chapter 4: Tables, Table Extensions & Data Modeling

4.1: Building Tables, Fields, Keys & Data Types 4.2: Table Extensions & Table Modifications 4.3: FlowFields, FlowFilters & Table Relations 4.4: Enums, Enum Extensions & Extensible Types

5 Chapter 5: Pages, Page Extensions & Role Centers

5.1: Page Types, Anatomy & Control Structure 5.2: Building Card, List & Document Pages 5.3: Page Extensions & Page Customizations 5.4: Role Centers, Headlines & Cue Data Modeling

6 Chapter 6: Reports & Document Generation

6.1 Report Architecture, DataItems & Dataset Design 6.2 Report Layouts: RDLC, Word, Excel & Multilanguage 6.3 Document Reports & Request Page Programming 6.4 Processing-Only Reports & Report Substitutions

7 Chapter 7: XMLports & Data Exchange

7.1 XMLport Architecture, Formats & Properties 7.2 XMLport Node Hierarchy, Triggers & Stream Manipulation

8 Chapter 8: Codeunits, Events, Triggers & Interfaces

8.1 Codeunit Types, Execution & SingleInstance Codeunits 8.2 Events, Publishers, Subscribers & Event Isolation 8.3 Interfaces, Polymorphism & Dynamic Codeunit Invocation 8.4 Installation & Upgrade Codeunits, Data Transfer & Archive

9 Chapter 9: Entitlements, Permissions & Queries

9.1 Permission Sets & Permission Set Extensions 9.2 Inherent Permissions, Inherent Entitlements & Security Scoping 9.3 Query Objects: Joins, Aggregation & Query as Report Data Source

10 Chapter 10: UI Customization, User Assistance & Onboarding

10.1 Profile Objects & Custom Page Views in AL 10.2 User Assistance: ToolTips, Teaching Tips & In-App Tours 10.3 Assisted Setup, Guided Experience & Onboarding Checklists

11 Chapter 11: Business Central Design Patterns & Data Process Model

11.1 Functional Table Types: Master Data, Supplemental & Setup Patterns 11.2 Document Standards: Header, Line, History & Journal Architectures 11.3 Data Process Model & Posting Routine Architecture

12 Chapter 12: AL Language Fundamentals, Data Types & Variables

12.1 AL Syntax, Variable Scope, Primitive & Complex Data Types 12.2 Expressions, Control Flow Statements & Built-in Functions 12.3 Access Modifiers (Public, Internal, Local) & Code Scoping

13 Chapter 13: Data Manipulation, Streams & Error Handling

13.1 Record Operations: Get, FindSet, ModifyAll & Filter Functions 13.2 Streams, File Management & TempBlob 13.3 Error Handling: ErrorInfo, TryFunctions & Collectible Errors

14 Chapter 14: Testing, Test Toolkit & Automation

14.1 Testing Architecture & the Test Toolkit 14.2 Authoring Test Codeunits & UI Handler Functions

15 Chapter 15: Telemetry, Performance Optimization & Analyzers

15.1 Telemetry Configuration & Azure Application Insights 15.2 Custom Telemetry Signals with Session.LogMessage & KQL 15.3 Performance Profiler, SetLoadFields & Query Optimization 15.4 AL Analyzers: CodeCop, AppSourceCop, UICop & PTECop

16 Chapter 16: REST Web Services & JSON in AL

16.1 HttpClient, HttpRequestMessage & REST API Consumption 16.2 JSON Processing: JsonObject, JsonArray, JsonValue & JsonToken

17 Chapter 17: API Pages, OData, Read Scale-Out & OAuth

17.1 API Pages (PageType=API), OData Web Services & REST Endpoints 17.2 Bound and Unbound OData Actions with [ServiceEnabled] 17.3 Read Scale-Out Architecture & DataAccessIntent Configuration 17.4 Microsoft Entra ID App Registrations & OAuth 2.0 Integration

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

Key Takeaways Explain This Topic AI

Business Central's modern user assistance framework employs a four-tiered hierarchy: Micro-Guidance (ToolTips), In-Context Callouts (Teaching Tips), Guided Workflows (In-App Tours), and Deep Conceptual Learning (External Help/Learn).

The ToolTip property is mandatory for AppSource marketplace certification on all interactive page controls and actions, requiring action-oriented phrasing that explains downstream business impact rather than repeating captions.

Teaching Tips are declared on pages, groups, fields, and actions using AboutTitle, AboutText, and AboutUrl properties to deliver contextual feature explanations and onboarding tips.

Business Central automatically synthesizes an interactive In-App Page Tour when page-level AboutTitle/AboutText properties are combined with control-level teaching tips across fields and actions.

Context-sensitive help connects UI pages to external documentation via ContextSensitiveHelpPage on pages and helpBaseUrl configured in app.json.

Last updated: August 2026

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)│
  • └─────────────────────────────────────────────────────────────┘

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.

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.

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.

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

Control Ineffective ToolTip (Avoid) Effective ToolTip (Recommended)

Field: "Reward Points" "Reward points." (Restates caption) "Specifies the total reward points accumulated by the customer that can be redeemed for invoice discounts."

Field: "Tier Code" "Code from Table 50100." (Technical jargon) "Specifies the membership tier that determines the discount percentage applied to sales documents."

Action: "Post Batch" "Posts records." (Vague) "Validates and posts all open loyalty journal lines simultaneously to the loyalty ledger."

Field: "Blocked" "Blocked status." (Restates caption) "Specifies whether transactions are blocked for this customer, preventing new sales orders from being created."

  • 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;
  • }
  • }
  • }
  • }

Loading diagram... Interactive In-App Tour Progression and Teaching Tip Chaining

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

Page-Level Teaching Tip : Declared at the root page level. It introduces the overall business concept of the page when the page is opened.

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

First-Time Discovery : When a user opens the page for the first time, the page-level teaching tip bubble appears automatically.

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 .

Spotlight Effect : While the tour is active, the Web Client dims the surrounding background and highlights (spotlights) the active control.

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 :

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"]
  • }

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

}