bc-tooltip-manager

name	bc-tooltip-manager
description	Automatically generate and set contextual tooltips for fields in Business Central pages and page extensions. Use when working with AL page objects (.Page.al) or page extensions (.PageExt.al) that need tooltip properties added or improved. Triggers when user asks to add tooltips, improve tooltips, generate tooltips for fields, or ensure all fields have proper user guidance.

Business Central Tooltip Manager

Overview

This skill enables intelligent generation and application of contextual tooltips for fields in Business Central pages and page extensions. It analyzes the page's functional purpose and field names to create meaningful, user-friendly tooltip text that follows Microsoft's best practices.

When to Use This Skill

Use this skill when:

• Adding tooltips to new page fields that lack them
• Improving existing tooltips that are generic or unhelpful
• Ensuring all fields in a page/page extension have proper tooltips
• Standardizing tooltip quality across multiple pages
• Working with page objects (.Page.al) or page extensions (.PageExt.al)

Core Workflow

Step 1: Identify Target Pages

Determine which pages need tooltip updates:

1. Single page: User specifies a specific page file
2. All pages in directory: Scan src/Page/ and src/Page Extension/ folders
3. Pages without tooltips: Use the scanner script to identify fields missing tooltips

Run the scanner script to find fields without tooltips:

python scripts/scan_tooltips.py --path "src/Page" --output "tooltip_report.json"

Step 2: Analyze Page Context

Before generating tooltips, understand the page's functional context:

1. Read the page object - Identify page type, source table, and purpose
2. Determine functional area - Sales, Purchasing, Finance, Inventory, etc.
3. Identify page pattern - Card, List, Document, Worksheet, Setup, etc.
4. Review related table - Check table field captions and data types

Example Context Analysis:

page 50100 "Sales Order Custom Fields"
{
  PageType = CardPart;
  SourceTable = "Sales Header";
  
  // Context: Sales domain, CardPart showing additional order fields
  // Fields should explain what data to enter and impact on order processing
}

Step 3: Generate Contextual Tooltips

Apply tooltip generation principles based on page context and field purpose.

Tooltip Formula

"Specifies [what the field represents] [contextual impact or usage]"

Examples:

Field Name	Page Context	Generated Tooltip
"Priority Level"	Sales Order	"Specifies the priority level for processing this sales order. High priority orders are processed first."
"Approval Status"	Purchase Invoice	"Specifies the approval status of the purchase invoice. The invoice cannot be posted until approved."
"Warehouse Location"	Item Card	"Specifies the default warehouse location where this item is stored."
"Payment Terms"	Customer Card	"Specifies the payment terms code that determines the due date and possible discount for the customer."

Contextual Patterns by Page Type

Card Pages (Master data):

• Focus on "what this represents" and "how it's used in transactions"
• Example: "Specifies the customer's default payment method for invoices."

Document Pages (Transactions):

• Focus on "impact on document processing" and "validation rules"
• Example: "Specifies the shipment date. The document cannot be posted with a future date."

List Pages (Overview):

• Focus on "filtering/sorting purpose" and "quick identification"
• Example: "Specifies the order status for filtering and tracking purposes."

Setup Pages (Configuration):

• Focus on "configuration impact" and "system behavior"
• Example: "Specifies whether to automatically create purchase orders from sales orders."

Worksheet Pages (Batch operations):

• Focus on "calculation/processing impact" and "data flow"
• Example: "Specifies the suggested quantity to order based on current inventory and demand."

Step 4: Apply Tooltips to AL Code

For each field requiring a tooltip, add or update the ToolTip property:

Pages (.Page.al)

field("Custom Field"; Rec."Custom Field")
{
  ApplicationArea = All;
  ToolTip = 'Specifies the custom field value for tracking additional order information.';
}

Page Extensions (.PageExt.al)

pageextension 50100 "Customer Card Extension" extends "Customer Card"
{
  layout
  {
    addafter(Name)
    {
      field("Customer Category"; Rec."Customer Category")
      {
        ApplicationArea = All;
        ToolTip = 'Specifies the customer category for segmentation and reporting purposes.';
      }
    }
  }
}

Step 5: Validate and Refine

After applying tooltips, validate quality:

1. Length check: Tooltips should be 1-2 sentences, typically 60-150 characters
2. Clarity check: Avoid technical jargon unless necessary
3. Consistency check: Similar fields across pages should have similar tooltip patterns
4. Standard format: Always start with "Specifies"
5. Value check: Tooltip adds meaningful context beyond the field caption

Tooltip Best Practices

Do's

✅ Always start with "Specifies" - This is Microsoft's standard convention

✅ Be specific and actionable - Tell users what to enter and why

✅ Include business impact - Explain how the field affects processing

✅ Use plain language - Write for end users, not developers

✅ Keep it concise - One or two sentences maximum

✅ Reference related features - Mention validation rules or dependencies

Don'ts

❌ Don't just repeat the caption - "Specifies the customer name" for field "Customer Name" is redundant

❌ Don't use technical jargon - Avoid "FK", "GUID", "blob", unless absolutely necessary

❌ Don't leave generic tooltips - "Specifies the value" is meaningless

❌ Don't exceed 200 characters - Keep tooltips scannable and readable

❌ Don't include UI instructions - Focus on data meaning, not "click here" guidance

Field Name to Tooltip Intelligence

Use these patterns to generate tooltips from field names:

Status Fields

• Field ending in "Status": Explain status values and progression
• Example: "Approval Status" → "Specifies the approval status. The document must be approved before posting."

Date/Time Fields

• Field containing "Date" or "Time": Explain when this date is set and its impact
• Example: "Shipment Date" → "Specifies when the items will be shipped to the customer."

Code Fields

• Field ending in "Code" or "No.": Explain what the code represents and where it's used
• Example: "Payment Terms Code" → "Specifies the payment terms that determine the due date calculation."

Boolean Fields

• Field starting with "Is", "Has", "Allow", "Enable": Explain the enabled/disabled behavior
• Example: "Allow Partial Shipment" → "Specifies whether the order can be shipped in multiple deliveries."

Amount/Quantity Fields

• Field containing "Amount", "Quantity", "Price": Explain calculation and usage
• Example: "Discount Amount" → "Specifies the total discount amount calculated from the discount percentage."

Reference Fields

• Field ending in "Name": If it references another entity, explain the relationship
• Example: "Salesperson Name" → "Specifies the salesperson responsible for this customer account."

Batch Operations

When updating multiple pages:

1. Group by functional area - Process all Sales pages together, then Purchasing, etc.
2. Maintain consistency - Use similar tooltip patterns for similar fields across pages
3. Test incrementally - Build and validate after each page to catch errors early
4. Document changes - Track which pages have been updated

Integration with AL Development

After Adding Tooltips

1. Build the project to check for syntax errors:

   al_build
   

2. Review problems to ensure no issues:

   @problems
   

3. Test in client - Hover over fields to verify tooltips display correctly

4. Check translation - If using multi-language, ensure tooltips are in translation files

Resources

Scripts

• scan_tooltips.py - Scans AL page files to identify fields missing tooltips
  • Usage: python scripts/scan_tooltips.py --path <directory> --output <report.json>
  • Output: JSON report of all fields without ToolTip property

References

• tooltip-patterns.md - Comprehensive patterns for different field types and contexts
• bc-terminology.md - Business Central terminology guide for consistent language

Example: Complete Page Tooltip Update

Before:

pageextension 50100 "Sales Order Extension" extends "Sales Order"
{
  layout
  {
    addafter("External Document No.")
    {
      field("Customer PO Number"; Rec."Customer PO Number")
      {
        ApplicationArea = All;
      }
      field("Requested Delivery Date"; Rec."Requested Delivery Date")
      {
        ApplicationArea = All;
      }
      field("Special Instructions"; Rec."Special Instructions")
      {
        ApplicationArea = All;
      }
    }
  }
}

After (with contextual tooltips):

pageextension 50100 "Sales Order Extension" extends "Sales Order"
{
  layout
  {
    addafter("External Document No.")
    {
      field("Customer PO Number"; Rec."Customer PO Number")
      {
        ApplicationArea = All;
        ToolTip = 'Specifies the customer''s purchase order number for reference on invoices and shipment documents.';
      }
      field("Requested Delivery Date"; Rec."Requested Delivery Date")
      {
        ApplicationArea = All;
        ToolTip = 'Specifies the delivery date requested by the customer. Use this to plan shipment and production schedules.';
      }
      field("Special Instructions"; Rec."Special Instructions")
      {
        ApplicationArea = All;
        ToolTip = 'Specifies any special handling or delivery instructions from the customer that should be communicated to the warehouse.';
      }
    }
  }
}

Common Scenarios

Scenario 1: New Page Extension with Custom Fields

User adds custom fields to a standard BC page but forgets tooltips.

Action:

1. Identify the page's functional context (e.g., Sales Order)
2. Analyze each custom field's purpose
3. Generate contextual tooltips following Sales domain patterns
4. Apply tooltips to all fields in the extension

Scenario 2: Standardizing Tooltips Across Module

Multiple pages in a custom module have inconsistent or missing tooltips.

Action:

1. Run scan_tooltips.py to identify all affected fields
2. Group pages by functional similarity
3. Establish consistent tooltip patterns for the module
4. Apply tooltips systematically, ensuring consistency
5. Build and validate after each functional group

Scenario 3: Improving Generic Tooltips

Existing tooltips are too generic (e.g., "Specifies the value").

Action:

1. Read the page and table context
2. Understand the field's business purpose
3. Replace generic tooltips with specific, contextual ones
4. Focus on business value and user guidance

Quality Checklist

Before completing tooltip work, verify:

• All visible fields have ToolTip property
• All tooltips start with "Specifies"
• Tooltips are specific to the field's purpose
• Tooltips explain business impact or usage
• Tooltips are 60-150 characters (1-2 sentences)
• Similar fields across pages have consistent patterns
• No technical jargon or developer terms
• No generic "Specifies the value" tooltips
• Project builds successfully after changes
• Tooltips display correctly in BC client

Notes

• Repeater/Grid fields: Tooltips in repeater sections help users understand data columns
• FlowFields: Explain calculation basis and what the sum/count represents
• FlowFilters: Explain filtering impact and how it affects calculations
• Actions: While this skill focuses on fields, consider adding tooltips to actions too
• Multi-language: Generated English tooltips should be added to translation files for localization