Introduction to Business Central Pages

Pages in Microsoft Dynamics 365 Business Central are the primary interface objects that users interact with. They provide a structured way to display, edit, and manage data from underlying tables.

Page Hierarchy

• Metadata Block: Defines overall page characteristics (PageType, SourceTable, properties)
• Layout Section: Describes visual components (areas, groups, fields, parts)
• Actions Section: Defines available actions, buttons, and navigation

Basic Page Structure

page 50101 "Customer List Simple"
{
    PageType = List;
    SourceTable = Customer;
    ApplicationArea = All;
    UsageCategory = Lists;
    Caption = 'Customer List';
    layout
    {
        area(Content)
        {
            field("No."; "No.") { ApplicationArea = All; }
        }
    }
}

Page Object Properties (Core)

Page Type Property

Defines the fundamental layout and behavior pattern.

Page Type	Description	Common Use
Card	Single-record detail view	Customer Card, Setup pages
List	Multiple records in table	Customer List, Item List
Document	Transaction header + lines	Sales Order, Purchase Invoice
Worksheet	Data entry grid with fields	General Journal
ListPlus	List with details panel	Sales Quotes with line details
API	Web service endpoint	REST API integration
RoleCenter	User landing page	Sales Manager Role Center
PromptDialog	AI Copilot interface	AI-assisted data entry

Source Table Property

• Purpose: Specifies the database table the page displays
• Required for most page types (except RoleCenter, NavigatePage)
• Cannot be changed in page extensions
• Example: SourceTable = Customer;

Caption Properties

• Caption: Page title (single language)
• CaptionML: Multi-language support
• Extensible: Yes

Caption = 'Customer List';
CaptionML = ENU='Customer List', ESP='Lista de clientes';

Data Manipulation Properties

• InsertAllowed: Controls record insertion (default: true)
• ModifyAllowed: Controls record modification
• DeleteAllowed: Controls record deletion
• Editable: Master switch for all field editability
• All support dynamic expressions: ModifyAllowed = Status <> Status::Posted;

Search and Discovery Properties

Usage Category

Makes pages discoverable through ‘Tell Me’ search. Requires ApplicationArea to be set.

• None: Not searchable (default)
• Lists: Customer lists, item lists
• Tasks: Task-oriented pages
• ReportsAndAnalysis: Reports and analytics
• Documents: Sales orders, invoices
• History: Posted documents
• Administration: Setup and configuration

UsageCategory = Lists;

Application Area

Controls feature visibility based on license level (Essential vs Premium).

• All: Always visible (recommended for most scenarios)
• Suite: Essential license features
• Advanced: Premium license features
• FixedAssets, Jobs: Specific functional areas
• Since BC 2022 Wave 2: Automatically inherits to all page fields

ApplicationArea = All; // Page-level (inherits to all fields)

Additional Search Terms

• Adds extra keywords for search
• Extensible: Yes
• Example: AdditionalSearchTerms = ‘client, debtor, account’;

API-Specific Properties

For PageType = API only. These properties configure the web service endpoint.

URL Structure Properties

Property	Purpose	Example
APIPublisher	Publisher name in URL	APIPublisher = ‘contoso’;
APIGroup	Logical grouping	APIGroup = ‘salesApp’;
APIVersion	Version identifier	APIVersion = ‘v1.0’;
EntitySetName	Plural name in URL (case-sensitive)	EntitySetName = ‘customers’;
EntityName	Singular name (metadata)	EntityName = ‘customer’;

Resulting URL: https ://{server}/api/contoso/salesApp/v1.0/companies({id})/customers

Critical API Properties

• ODataKeyFields: Defines unique record identifier – ALWAYS use SystemId
• DelayedInsert: MUST be true for editable API pages (batches field values before insert)
• EntitySetName: Case-sensitive in URLs
• APIPublisher: Case-insensitive for HTTP but case-sensitive for webhook subscriptions

ODataKeyFields = SystemId; // Immutable, globally unique
DelayedInsert = true;      // Required for APIs

Complete API Page Example

page 50200 "Customer API"
{
    PageType = API;
    APIPublisher = 'contoso';
    APIGroup = 'salesApp';
    APIVersion = 'v1.0';
    EntityName = 'customer';
    EntitySetName = 'customers';
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    SourceTable = Customer;
}

Page Field Properties

Field properties control individual field behavior, appearance, and validation.

Display Properties

Property	Purpose	Extensible
Caption/CaptionML	Override table field caption for this page	Yes
ToolTip/ToolTipML	Hover help text	Yes
Visible	Show/hide field	Yes
Enabled	Enable/disable editing (grayed when false)	Yes
Show Caption	Display field label	Yes
Importance	Standard/Promoted/Additional	Yes
Style/Style Expr	Visual styling (colors, emphasis)	Yes

ToolTip Best Practices

• Since BC 2024 Wave 1: ToolTips on table fields automatically inherit to pages
• Format: ‘Specifies…’ or ‘Defines…’
• Example: ToolTip = ‘Specifies the customer\’s phone number’;

Importance Values

• Standard: Always shown (default)
• Promoted: Highlighted/emphasized
• Additional: Hidden under ‘Show more fields’

Style Values

• None, Standard, StandardAccent
• Strong, StrongAccent
• Attention, AttentionAccent
• Favorable, Unfavorable (for amounts)
• Ambiguous, Subordinate

Style = Strong;
StyleExpr = GetStyleExpression(); // Dynamic styling

Data Entry Properties

Property	Purpose	Example
Editable	Field-level edit control	Editable = Status = Status::Open;
QuickEntry	Include in tab navigation	QuickEntry = false;
ShowMandatory	Visual highlight for required fields	ShowMandatory = true;
NotBlank	Enforce value required	NotBlank = true;
MultiLine	Multi-line text input	MultiLine = true;
Lookup	Enable lookup (F6/dropdown)	Lookup = true;
DrillDown	Enable drill-down (clickable link)	DrillDown = true;
AssistEdit	Add assist-edit button (…)	AssistEdit = true;

Formatting Properties

Decimal Places

DecimalPlaces = 2:2;  // Always 2 decimals

DecimalPlaces = 0:5;  // Variable, up to 5

Display Options

• BlankZero: Display zero values as blank
• BlankNumbers: Control display of different number types
• ClosingDates: Enable accounting period closing dates

Relationship Properties

Table Relation

Defines relationships to other tables (enables validation, lookup).

// Simple relation
TableRelation = Customer;
// Conditional relation
TableRelation = IF (Type = CONST(Item)) Item
                ELSE Resource;

Navigation Properties

• LookupPageId: Page shown for lookup
• DrillDownPageId: Page shown when drilling down
• Both are extensible

LookupPageId = "Customer List";
DrillDownPageId = "Customer Card";

Page Extension Properties

Page extensions allow modification of existing pages. Only pages with Extensible = true can be extended.

Extensible Properties

Properties marked ‘Extensible = True’ can be modified in page extensions:

Display Properties

• Caption, CaptionML, ToolTip, ToolTipML
• Visible, Enabled, Importance, ShowCaption
• Style, StyleExpr

Behavior Properties

• InsertAllowed, ModifyAllowed, DeleteAllowed
• ApplicationArea, QuickEntry, ShowMandatory
• Editable (since BC 2025 Wave 2+ in customizations)

Help & Search

• ContextSensitiveHelpPage, AdditionalSearchTerms
• AboutText, AboutTextML, AboutTitle, AboutTitleML

Non-Extensible Properties

Core structural properties CANNOT be changed:

• PageType, SourceTable, SourceTableTemporary
• ODataKeyFields, Extensible
• API properties (APIPublisher, APIGroup, etc.)
• Lookup, DrillDown (on fields)

Page Extension Example

pageextension 50100 CustomerListExt extends "Customer List"
{
    // Modify page-level property
    AdditionalSearchTerms = 'client, account';
    layout
    {
        // Add new field
        addafter(Name)
        {
            field("E-Mail"; "E-Mail")
            {
                ApplicationArea = All;
                ToolTip = 'Specifies the customer email';
            }
        }
        // Modify existing field
        modify("Phone No.")
        {
            Importance = Promoted;
            ShowMandatory = true;
        }
    }
}

Best Practices

General Recommendations

• Always set ApplicationArea = All; at page level (inherits to fields since BC 2022 Wave 2)
• Provide meaningful ToolTips starting with ‘Specifies…’ or ‘Defines…’
• Use UsageCategory with ApplicationArea to enable Tell Me search
• Leverage property inheritance: define tooltips on table fields (BC 2024+)
• For API pages: ALWAYS set DelayedInsert = true for editable pages
• Use SystemId for ODataKeyFields (immutable, globally unique)

Performance Tips

• Use Importance = Additional for rarely-used fields
• Set DataAccessIntent = ReadOnly for read-only pages
• Minimize visible FlowFields; consider caching strategies

User Experience

• Dynamic visibility: Visible = Type = Type::Item;
• Conditional editability: Editable = Status <> Status::Posted;
• Visual feedback: Use Style = Favorable/Unfavorable for amounts
• Quick entry: Set QuickEntry = false on calculated/auto-filled fields

API Development

• Use SystemId for ODataKeyFields (not business keys)
• Never break existing API versions; create new versions for breaking changes
• Expose lastModifiedDateTime field (exact name) for webhook functionality
• Use camelCase for EntitySetName and field names
• EntitySetName is case-sensitive in URLs

Troubleshooting Common Issues

Field Not Visible

• Check ApplicationArea is set (required in cloud)
• Verify Visible = true or expression evaluates to true
• Check Company Information > Experience matches ApplicationArea (Essential vs Premium)
• Fields with Importance = Additional may be under ‘Show more’

Field Not Editable

• Page-level Editable = false overrides all fields
• Check field-level Editable property
• Enabled = false shows grayed-out field
• Verify user has modify permissions on the table

API Issues

• Missing DelayedInsert: Error on POST – ensure DelayedInsert = true
• Case-sensitive EntitySetName in URLs
• APIPublisher: case-insensitive for HTTP, case-sensitive for webhooks
• Webhook not working: ensure ‘lastModifiedDateTime’ field (exact name) is exposed

Extension Errors

• Cannot extend: base page must have Extensible = true
• Cannot modify property: only Extensible = True properties can be changed
• Name too long: extension names limited to 30 characters

Common Compiler Errors

Error Code	Issue	Solution
AL0167	ApplicationArea requires UsageCategory	Set UsageCategory for searchability
AL0246	ApplicationArea cannot be customized	Property restricted in context
AS0062/PTE0008	ApplicationArea inheritance rules	Since BC 2022 Wave 2, fields inherit from page

Property Quick Reference

Most Commonly Used Page Properties

Property	Type	Extensible	Description
PageType	Page	No	Card, List, Document, API, etc.
SourceTable	Page	No	Database table
ApplicationArea	Both	Yes	Feature visibility (All, Suite, Advanced)
UsageCategory	Page	No	Tell Me searchability
Caption/CaptionML	Both	Yes	Display title
Editable	Both	Yes	Edit control
InsertAllowed	Page	Yes	Allow inserts
ModifyAllowed	Page	Yes	Allow modifications
DeleteAllowed	Page	Yes	Allow deletions
DelayedInsert	Page	No	Required for API pages

Most Commonly Used Field Properties

Property	Extensible	Description
ToolTip/ToolTipML	Yes	Hover help text
Visible	Yes	Show/hide field
Enabled	Yes	Enable/disable editing
Importance	Yes	Standard/Promoted/Additional
QuickEntry	Yes	Include in tab navigation
ShowMandatory	Yes	Visual highlight for required
TableRelation	Yes	Relationship to other tables
LookupPageId	Yes	Lookup page
Style/StyleExpr	Yes	Visual styling

API-Specific Properties

Property	Required	Example
PageType	Yes	PageType = API;
APIPublisher	Yes	APIPublisher = ‘contoso’;
APIGroup	Yes	APIGroup = ‘salesApp’;
APIVersion	Yes	APIVersion = ‘v1.0’;
EntityName	Yes	EntityName = ‘customer’;
EntitySetName	Yes	EntitySetName = ‘customers’;
ODataKeyFields	Yes	ODataKeyFields = SystemId;
DelayedInsert	Yes	DelayedInsert = true;

Conclusion

This blog has provided a comprehensive overview of Business Central page, page field, and page extension properties. Key takeaways:

• Property Inheritance: Leverage automatic inheritance (ApplicationArea, ToolTips) to reduce duplication
• Extensibility: Always check which properties are extensible before planning customizations
• API Best Practices: Use SystemId for keys, enable DelayedInsert, follow naming conventions
• User Experience: Provide tooltips, use dynamic visibility, optimize quick entry
• Documentation: Keep captions, tooltips, and help links current