Teach your users tips with teaching tips!

In this video, I show how to welcome your users to a new page with teaching tips to guide them through the content and functionality, check it out:

https://youtu.be/RIfHTyf9RNo

In this video, Erik explores the teaching tips feature in AL for Business Central — a way to guide users through your pages with contextual tips and tours. He walks through adding teaching tips to various UI elements including pages, fields, actions, parts, and factboxes, while discovering the ordering behavior and limitations along the way.

What Are Teaching Tips?

Teaching tips are contextual hints that appear when a user first opens a page or clicks/hovers on the page title. They provide a guided tour of the page, highlighting different elements and explaining their purpose. You’ve likely seen them on standard Business Central pages like the Customer Card, where tips describe sections like “Invoicing” and “Payments” as you click through the tour.

The teaching tip tour walks users through different areas of a page, with callout bubbles that point to the relevant UI elements. Users can click “Take a tour” to step through all the tips, and later “Retake the tour” if they want to see them again.

Adding Teaching Tips to a Page

Erik demonstrates using his Point of Sale sample app. The first step is adding a teaching tip to the page itself. You might expect the property to be called TeachingTipTitle, but it’s actually called AboutTitle and AboutText:

page 50100 "Point of Sale"
{
    AboutTitle = 'Welcome to Point of Sale';
    AboutText = 'Start scanning items from this screen to quickly sell a lot of stuff in your nice shop.';
    
    // ... rest of the page
}

When you deploy and open the page, the teaching tip appears with your title and text. The “Learn more” link takes users to whatever URL is configured in your app.json under the context-sensitive help URL — so make sure that’s set to something meaningful and not just a default placeholder.

Teaching Tips on Fields

Next, Erik adds a teaching tip to a field on the page:

field("Receipt Status"; Rec."Receipt Status")
{
    AboutTitle = 'Receipt Status';
    AboutText = 'Here you can see if you have an active receipt.';
}

When taking the tour, the callout bubble now points directly at the field — a nice touch that helps users understand exactly what’s being described.

He also adds a tip to the customer field:

field("Customer No."; Rec."Customer No.")
{
    AboutTitle = 'Specify the Customer';
    AboutText = 'If you are not selling with cash payment, then you can specify a customer here.';
}

Teaching Tips on Actions

Actions support teaching tips as well. Erik adds tips to two actions — “Start a New Receipt” and “Pay”:

action(NewReceipt)
{
    AboutTitle = 'Start a New Receipt';
    AboutText = 'Click here to start a new receipt, or you can just start scanning if you have a scanner.';
    // ...
}

action(Pay)
{
    AboutTitle = 'Receive Payment';
    AboutText = 'Click pay to receive payment from the customer.';
    // ...
}

The teaching tip callout points directly at the action button in the action bar.

Teaching Tips on Parts and Factboxes

Parts (subforms) and factboxes also support teaching tips. Erik adds a tip to the lines part and the totals factbox part:

part(Lines; "POS Lines Subform")
{
    AboutTitle = 'Receipt Lines';
    AboutText = 'Here are all the items on the receipt that have been entered or scanned.';
    // ...
}

part(Totals; "POS Totals Factbox")
{
    AboutTitle = 'Receipt Totals';
    AboutText = 'Here you can check the total of the receipt during entry and scanning.';
    // ...
}

Teaching Tips on Fields Inside Subpages

An interesting discovery: you can add teaching tips to fields within a subpage (list part), but you cannot add them to the subpage itself using the AboutTitle/AboutText at the page level of the subpage. You need to put the tip on the part control on the parent page, or on individual fields within the subpage:

// Inside the subpage definition
field(Quantity; Rec.Quantity)
{
    AboutTitle = 'Item Quantity';
    AboutText = 'If you scan the same item twice, it will update the existing line with a larger quantity instead of adding a new line.';
}

Similarly, fields inside a factbox page can have their own teaching tips:

// Inside the factbox page
field("Amount Including Tax"; Rec."Amount Including Tax")
{
    AboutTitle = 'Remember This';
    AboutText = 'This total is including tax.';
}

Tour Order: How It Works

Erik experiments extensively with the ordering of teaching tips during the tour. Through trial and error, he discovers the following order:

  1. Content fields — Fields on the main page, in the order they appear in the code
  2. Parts (subforms) — Including fields within subpages
  3. Actions — In the order they appear in the code
  4. Factbox parts — Including fields within factbox pages

Importantly, the order within each category follows the order of the code, not alphabetical order. Erik confirmed this by rearranging actions in the source code and observing the tour order change accordingly.

Limitations and Observations

  • No explicit order control: There is no property to specify the sequence number for teaching tips. The order is determined by the element type (content → parts → actions → factboxes) and then by code order within each group.
  • Some elements don’t support teaching tips: Erik found that certain places in the UI won’t accept AboutTitle/AboutText. Promoted actions created with the newer PromotedOnly syntax may behave differently.
  • The “Learn more” URL comes from your app.json context-sensitive help URL — double-check this is set correctly, especially if you started from a template project.
  • Generic system tips (like “Open a new window”) are appended to the tour automatically by the platform.

The app.json Configuration

Here’s the project’s app.json for reference. Note the importance of the help URL and context-sensitive help configuration, as this is where the “Learn more” link in teaching tips will direct users:

{
  "id": "ded6e99e-5d8a-45c9-a5b5-4115bbc191d1",
  "name": "TipsToSomethingWithoutTips",
  "publisher": "Default publisher",
  "version": "1.0.0.0",
  "brief": "",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "dependencies": [],
  "platform": "1.0.0.0",
  "application": "20.0.0.0",
  "idRanges": [
    {
      "from": 50100,
      "to": 50149
    }
  ],
  "resourceExposurePolicy": {
    "allowDebugging": true,
    "allowDownloadingSource": false,
    "includeSourceInSymbolFile": false
  },
  "runtime": "9.0"
}

Summary

Teaching tips are a powerful and underutilized feature in AL for Business Central. By adding AboutTitle and AboutText properties to pages, fields, actions, parts, and factbox elements, you can create guided tours that walk users through your pages. The tour order follows a predictable pattern — content fields first, then parts, then actions, then factboxes — with the order within each group determined by the position in your AL code.

While there are some limitations (no explicit ordering control, some UI elements not yet supported), teaching tips are an excellent way to take users by the hand and guide them through complex pages. As Erik puts it, we have a tendency to build complicated pages, and teaching tips offer a way to make those pages less intimidating for users encountering them for the first time.

Picture of hougaard

hougaard