Dimension support must follow the DimensionManagement wiring pattern

Description

Wiring a new custom master table or document table into Business Central's dimension system isn't a matter of adding a Code[20] field and calling it done — it requires a specific set of hooks into DimensionManagement (codeunit 408) so the value is validated, persisted, and flows into transactions the same way it does for every standard master/document table. Skipping any one of these hooks produces a dimension field that looks right in the designer but silently fails to save, validate, or carry through to postings.

Wiring a Master Table (e.g. a new "Instructor" or "Course" table)

Fields: add Global Dimension 1 Code / Global Dimension 2 Code (Code[20]), each with TableRelation = "Dimension Value".Code where("Global Dimension No." = const(1/2), Blocked = const(false)) and CaptionClass set to '1,1,1' / '1,1,2' — this is what lets Codeunit 42 (Caption Class) show the company's actual dimension name (e.g. "Department Code") instead of the generic field name.
Validation: add a ValidateShortcutDimCode function that calls DimensionManagement.ValidateDimValueCode then DimensionManagement.SaveDefaultDim; call it from each dimension field's OnValidate trigger.
Lifecycle: the table's OnInsert/OnDelete triggers must call DimensionManagement to create/delete the corresponding Default Dimension (table 352) records tied to that master record — the master record and its default dimensions must be created and destroyed together.
Table ID registration: if the master table's key is referenced through a TypeToTableID-style option in DimensionManagement (SetupObjectNoList/TableIDArray), that logic must be extended to include the new table, or dimension lookups involving it will resolve to the wrong table.

Wiring a Document Table (header/line)

Add Shortcut Dimension 1 Code / Shortcut Dimension 2 Code fields (the remaining six shortcut dimensions are entered through a separate Dimensions window, not as physical fields). Call ValidateShortcutDimCode from each field's OnValidate. Call a CreateDim function — which pulls dimension values from the related master record — whenever the field that attaches the document to a master record changes (e.g. when Bill-to Customer No. changes on a header, or when a line's Type/No. changes). This is the same model the Sales Header table uses when the Bill-to Customer changes.

Review Checklist

Do the dimension fields have the correct TableRelation filtered to Global Dimension No. = 1/2 and Blocked = false, and the matching CaptionClass?
Is ValidateShortcutDimCode wired to each dimension field's OnValidate — not left to a bare TableRelation with no validation?
Do OnInsert/OnDelete create/delete the Default Dimension records, so master records and their dimensions can't get out of sync?
If the table is referenced via a TypeToTableID-style option, was SetupObjectNoList/TableIDArray actually extended?
For a document table: does CreateDim run whenever the master-record-attaching field changes, so dimensions flow in automatically rather than requiring the user to re-enter them?

Source

CURABIS Academy course "The Developers Guide through AL" (rev. July 2022), Chapter 8: Dimensions & Debugging, "Code Walkthrough - Dimension Management Codeunit", "Solution Design - DimensionManagement Codeunit", "Solution Design - Global Dimension Fields", "Dimensions in Documents", "Solution Design - Shortcut Dimension Fields" (p. 262–268). Cross-checked against the current Base Application DimensionManagement codeunit (408) and the Customer/Sales Header table wiring as of 2026-08-13 — the pattern still holds.

4 KiB Raw Blame History Unescape Escape