Microsoft/bcquality
1
0
Fork 0
mirror of https://github.com/microsoft/BCQuality.git synced 2026-10-05 06:36:55 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
bcquality/microsoft/knowledge/data-modeling/dimension-management-wiring.md
Michael Dieringer 43c9d5319c Fix two merge-critical correctness issues from Jesper's 2026-09-22 review 
- api-page-key-fields-must-be-editable-on-insert.good.al and
  stored-derived-fields-must-not-be-exposed-directly.good.al: both were
  writable API pages missing DelayedInsert = true, contradicting this
  repo's own api-page-delayedinsert-true rule - the canonical "good"
  samples were teaching code BCQuality itself flags.
- dimension-management-wiring.good.al: UpdateDimensionSetID exited
  early when Customer.Get failed, leaving the previous customer's
  shortcut dimension and Dimension Set ID in place - the same staleness
  bug the InheritFromDimSetID = 0 fix (from the prior review round) was
  meant to prevent, just triggered by a failed lookup instead of a
  successful one. Now clears the shortcut field and recomputes with an
  empty source list on a failed lookup too, so GetDefaultDimID
  correctly returns an empty Dimension Set ID instead of never running.
2026-09-22 14:32:35 +02:00

4.1 KiB
Raw Blame History

bc-version domain keywords technologies countries application-area
all
data-modeling
dimensions
dimensionmanagement
global-dimension
shortcut-dimension
default-dimension
validatedimvaluecode
getdefaultdimid
al
w1
all

Wire dimension support through DimensionManagement, not ad hoc fields

Contributions welcome — open a PR to refine or extend this article.

Description

Adding dimension support to a custom table is not just a matter of adding a Code[20] field, and master tables and document/transactional tables wire into Codeunit "Dimension Management" through two different models — treating them as one mechanism is itself the mistake this article corrects:

  • Master data (a custom master table, e.g. "Course") persists Default Dimension records: each shortcut dimension field validates through ValidateDimValueCode, then the result is saved via SaveDefaultDim, and DeleteDefaultDim removes them again in OnDelete. Both ValidateDimValueCode and SaveDefaultDim take the shortcut dimension number (1-8, matching General Ledger Setup's "Shortcut Dimension N Code" fields) as their first/third argument respectively — not the AL field ID of the table field being validated. The master record itself carries no Dimension Set ID field.
  • Transactional/document data (a custom document or journal-line table) carries a single Dimension Set ID field — a pointer to a shared, deduplicated set of dimension values in Dimension Set Entry, assembled from whatever the document inherited plus whatever the user overrode. A document does not acquire that ID by calling SaveDefaultDim; it builds a source list with AddDimSource (naming the related master table and its key, e.g. Database::Customer), then calls GetDefaultDimID to compute a new Dimension Set ID that inherits the master's Default Dimension records. Editing a shortcut dimension field directly on the document validates through ValidateShortcutDimValues, which updates the same Dimension Set ID in place rather than writing a separate Default Dimension record.

Skipping the model that actually matches the table's kind produces a field that looks correct in the designer but silently fails to save, validate, or carry through to postings — or, for a document, one that never picks up the customer's/vendor's own dimensions at all.

Best Practice

For a master table, validate each shortcut dimension field through ValidateDimValueCode, save the result with SaveDefaultDim, and delete the matching Default Dimension records in OnDelete.

For a document table, when the field that attaches the document to a master record changes (e.g. Customer No.), call AddDimSource naming that master table and key, then GetDefaultDimID to compute the document's new Dimension Set ID, inheriting the master's Default Dimension records. Pass 0 for GetDefaultDimID's InheritFromDimSetID argument in this case — passing the document's existing Dimension Set ID instead inherits whatever dimensions were already in it, so a value the previous linked record supplied can survive into the new one even where the new record has no default for that dimension. Run this same recompute — clear the shortcut field, call GetDefaultDimID with no source added — when the lookup on the new key fails (blank or an invalid value), too: exiting early instead leaves the previous record's dimensions in place, which is the same staleness bug the InheritFromDimSetID = 0 rule exists to prevent. Validate the document's own Shortcut Dimension fields through ValidateShortcutDimValues, which updates that same Dimension Set ID in place rather than persisting a separate Default Dimension record.

See sample: dimension-management-wiring.good.al.

Anti Pattern

Adding a dimension-looking field with only a TableRelation to Dimension Value, and no call into DimensionManagement at all. The field accepts input but never becomes a real Default Dimension record, so it does not validate against blocked values and does not flow into postings.

See sample: dimension-management-wiring.bad.al.