4.2: Table Extensions & Table Modifications

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

4.2: Table Extensions & Table Modifications

Key Takeaways Explain This Topic AI

Table extensions (tableextension) extend existing base tables without modifying core source code, creating SQL companion tables linked 1:1 on the primary key.

Developers can add new fields and secondary keys, and modify specific field properties such as TableRelation, Caption, and Editable via the modify block.

Base field data types, lengths, field IDs, and primary key membership cannot be changed in a table extension.

Table extensions support OnBeforeValidate and OnAfterValidate triggers on existing base fields, as well as table-level triggers like OnBeforeInsert and OnAfterInsert.

The companion table architecture incurs SQL JOIN overhead; developers should use SetLoadFields and partial records to avoid loading unused extension columns.

Last updated: August 2026

4.2 Table Extensions & Table Modifications

In modern Dynamics 365 Business Central development, the base application source code is immutable. To customize existing standard tables (such as Customer , Vendor , Item , or Sales Line ), developers create tableextension objects. Table extensions allow you to introduce custom fields, build new secondary keys, modify permissible field properties, and hook custom logic into validation and table triggers.

1. Table Extension Architecture & Companion Tables

Under the non-intrusive extension model, Business Central implements table extensions using the Companion Table Pattern in Microsoft SQL Server.

How Companion Tables Work Under the Hood

When you publish a table extension that adds new fields to table Customer (Table 18), the database engine does not alter the core [dbo].[Customer] SQL table.

Instead, SQL Server creates a separate companion table named [dbo].[Customer$AppGuid] .

The companion table shares the exact same primary key column(s) as the base table.

When an AL query or page reads a record that references both base fields and extension fields, the Business Central Server (NST) automatically issues an SQL JOIN on the primary key. tableextension 50100 "Customer Loyalty Ext" extends Customer

• {
• fields
• {
• field(50100; "Loyalty Tier Code"; Code[20])
• {
• Caption = 'Loyalty Tier Code';
• DataClassification = CustomerContent;
• TableRelation = "Loyalty Tier"."Code";

• trigger OnValidate()
• begin
• // Validation logic for custom field
• end;
• }
• field(50101; "Loyalty Points"; Integer)
• {
• Caption = 'Loyalty Points';
• DataClassification = CustomerContent;
• MinValue = 0;
• }
• }

• keys
• {
• key(LoyaltyKey; "Loyalty Tier Code", "Loyalty Points")
• {
• }
• }

• trigger OnBeforeInsert()
• begin
• if "Loyalty Tier Code" = '' then
• "Loyalty Tier Code" := 'BRONZE';
• end;

• trigger OnAfterInsert()
• begin
• end;
• }

Loading diagram... Companion Table SQL Architecture

2. Modifying Existing Base Table Fields

AL table extensions allow developers to modify specific properties of existing base fields using the modify block. However, strict boundaries apply to ensure stability across extensions and base application upgrades.

Permissible vs Forbidden Modifications

Action / Property Allowed via modify ? Technical Rationale

TableRelation YES You can redirect or refine foreign key lookups (e.g., adding conditional table relations).

ValidateTableRelation YES Enable or disable referential validation on table relations.

Caption / CaptionML YES Allows localization or terminology customization for specific customer industries.

OptionCaption YES Modifies display text of legacy option members without altering underlying ordinals.

Editable YES Can change field editability from true to false (or false to true if base allows).

NotBlank YES Can make an optional field required on UI entry.

LookupPageId / DrillDownPageId YES Redirects field lookups to custom page objects.

Data Type change NO Changing field type would corrupt existing SQL storage and break dependent apps.

Field Length (Text/Code) NO Cannot expand or reduce length of base fields in table extensions.

Field ID or Field Name NO Base identifiers are immutable across extensions.

Primary Key membership NO Primary key columns cannot be added or removed from base tables.

AutoIncrement NO Cannot be altered on base fields.

• Syntax for Modifying Base Fields and Triggers tableextension 50101 "Item Modification Ext" extends Item
• {
• fields
• {
• modify("Description 2")
• {
• Caption = 'Secondary Brand Name';
• TableRelation = "Brand Code"."Code";
• NotBlank = true;

• trigger OnBeforeValidate()
• begin
• // Executes BEFORE the base table OnValidate trigger
• end;

• trigger OnAfterValidate()
• begin
• // Executes AFTER the base table OnValidate trigger
• end;
• }
• }
• }

3. Adding Keys & Indexing Rules in Table Extensions

Developers can define secondary keys in table extensions to support fast filtering and sorting on custom fields or combinations of custom and base fields.

Key Rules for Table Extensions

Secondary Keys Only: You can only add secondary keys. You cannot define a new primary key or alter the base clustered primary key.

Mixed Key Columns: A key in a table extension can contain:

Only custom fields defined in the same table extension.

A mixture of custom fields and base fields.

Only base fields (creating a new index on base columns).

SumIndexFields & IncludedFields: You can define SumIndexFields (for SIFT aggregates) and IncludedFields (for SQL covering indexes) on secondary keys in table extensions.

Unique Constraint Limitation: Defining Unique = true on a key in a table extension is only supported if all fields in the key belong to the extension table, or if the primary key fields are included. Unique indexes spanning base and companion tables cannot be enforced directly at the SQL level without primary key coverage.

4. Trigger Execution Sequence & Lifecycle Management

When a record operation occurs on an extended table, Business Central executes triggers and event subscribers in a strictly deterministic sequence.

• Validation & Modification Lifecycle 1. Field :: OnBeforeValidate (Table Extension)
• 2. Field :: OnValidate (Base Table)
• 3. Field :: OnAfterValidate (Table Extension)
• 4. Table :: OnBeforeModify / OnBeforeInsert (Table Extension)
• 5. Table :: OnModify / OnInsert (Base Table)
• 6. Table :: OnAfterModify / OnAfterInsert (Table Extension)
• 7. Database Commit & Global Event Subscribers (Codeunits)
• Schema Evolution with Obsolete Properties

When refactoring or deprecating fields in table extensions, deleting fields directly causes breaking schema changes. Business Central mandates non-destructive schema evolution using the ObsoleteState property: field(50105; "Legacy Rating"; Code[10])

• {
• Caption = 'Legacy Rating';
• DataClassification = CustomerContent;
• ObsoleteState = Pending;
• ObsoleteReason = 'Replaced by Loyalty Tier Code (field 50100) in v2.0.';
• ObsoleteTag = 'v2.0';
• }

ObsoleteState = Pending : Emits compiler warnings when developers reference the field. The field remains accessible in the database.

ObsoleteState = Removed : The field can no longer be referenced in AL code. The runtime prevents access while preserving database migration pathways.