The reason is that dimensions in D365 F&O are not stored as strings. They are stored as RecId references to normalised sets in the dimension framework tables. Understanding this storage model — and knowing which of the dozen-plus facade classes to use in each situation — is the entire battle.
This article covers the framework from the inside out: the data model, the difference between default dimensions and ledger dimensions, every key API with its correct signature, and a set of production-grade X++ patterns for the scenarios you will encounter in real implementations.
The two dimension types you must distinguish
Every confusion in the dimension framework traces back to not distinguishing between these two things:
Both types are stored as RecId values pointing into the dimension framework tables. You cannot read or write them with plain strings. You must use the facade APIs.
The data model — what is behind the RecId
Understanding what the RecId actually points to explains why the framework behaves the way it does — especially its immutability.
Why dimension data is immutable
Dimension records are never updated or deleted — only inserted. When you change a dimension value on a record, the framework creates a new DimensionAttributeValueSet record and links the record to the new set. The old set remains in the database for historic transactions. This is why you must never write to these tables directly — only through the facade APIs.
Assigning a raw string or a hardcoded numeric value to LedgerJournalTrans.LedgerDimension or any DefaultDimension field compiles and runs without error — but produces either a zero RecId (unresolved account) or a stale reference at posting time. Always use the facade APIs to build dimension values.
Part 1 — Reading dimension values from existing records
Read a specific dimension value from a default dimension
The most common read scenario: given a record's DefaultDimension RecId, extract the value of a specific dimension attribute (e.g. Cost Centre, Department).
/// Read a single dimension attribute value from a DefaultDimension set
public static DimensionValue getDimensionValueFromDefaultDim(
DimensionDefault _defaultDimension,
Name _dimensionAttributeName)
{
DimensionAttributeValueSetItemView dimView;
DimensionAttribute dimAttribute;
select firstonly DisplayValue from dimView
where dimView.DimensionAttributeValueSet == _defaultDimension
exists join dimAttribute
where dimAttribute.RecId == dimView.DimensionAttribute
&& dimAttribute.Name == _dimensionAttributeName;
return dimView.DisplayValue;
}
// Usage
VendTable vendTable = VendTable::find('US-001');
DimensionValue costCentre = getDimensionValueFromDefaultDim(
vendTable.DefaultDimension,
'CostCenter');
info(strFmt("Cost Centre on vendor US-001: %1", costCentre));
DimensionAttributeValueSetItemView is a view that joins DimensionAttributeValueSetItem with DimensionAttributeValue and exposes DisplayValue directly. Using this view is both cleaner and safer than joining the underlying tables manually.
Read dimensions using SQL (for debugging or reporting)
Useful for quickly inspecting dimension values in a sandbox environment.
SELECT DA.NAME, V.DISPLAYVALUE FROM DIMENSIONATTRIBUTEVALUESETITEMVIEW V JOIN DIMENSIONATTRIBUTE DA ON DA.RECID = V.DIMENSIONATTRIBUTE WHERE V.DIMENSIONATTRIBUTEVALUESET = -- paste the DefaultDimension RecId hereGet display value from a ledger dimension
To read the full formatted account string (e.g. 110180-007-023) from a LedgerDimension RecId:
// Get the display string from a ledger dimension RecId
LedgerDimensionAccount ledgerDim = ledgerJournalTrans.LedgerDimension;
str displayValue = LedgerDimensionFacade::getDisplayValueForLedgerDimension(ledgerDim);
// Returns: "110180-007-023" (main account + all dimension segments)
// Get just the main account Id
MainAccountNum mainAccountNum = LedgerDimensionFacade::getMainAccountIdFromLedgerDimension(ledgerDim);
// Returns: "110180"
// Get the main account RecId (for joins)
RecId mainAccountRecId = LedgerDimensionFacade::getMainAccountRecIdFromLedgerDimension(ledgerDim);
// Extract the default dimension set from a ledger dimension
DimensionDefault dimDefault = LedgerDimensionFacade::getDefaultDimensionFromLedgerDimension(ledgerDim);
Part 2 — Writing a single dimension value to a default dimension
This is the most common write scenario: you have an existing record and you need to set or update one dimension value (e.g. stamp a cost centre on a custom record when a business event triggers).
The correct class is DimensionAttributeValueSetStorage. Never write to DimensionAttributeValueSetItem or related tables directly.
/// Set a single dimension attribute value on an existing DefaultDimension set.
/// Returns the new DefaultDimension RecId.
public static DimensionDefault setDefaultDimensionValue(
DimensionDefault _existingDefaultDim,
Name _dimensionAttributeName,
DimensionValue _value)
{
DimensionAttributeValueSetStorage dimStorage;
DimensionAttribute dimAttribute;
DimensionAttributeValue dimAttributeValue;
// Load the existing dimension set into the storage class
dimStorage = DimensionAttributeValueSetStorage::find(_existingDefaultDim);
// Find the dimension attribute by name
dimAttribute = DimensionAttribute::findByName(_dimensionAttributeName);
if (!dimAttribute)
{
throw error(strFmt("Dimension attribute '%1' not found.", _dimensionAttributeName));
}
if (_value)
{
// Find or create the dimension attribute value
dimAttributeValue = DimensionAttributeValue::findByDimensionAttributeAndValue(
dimAttribute,
_value,
false, // do not create if not found
true); // throw error if not found
dimStorage.addItem(dimAttributeValue);
}
else
{
// Clear this dimension from the set
dimStorage.removeDimensionAttribute(dimAttribute.RecId);
}
// Save returns a new RecId (immutable — always a new set record)
return dimStorage.save();
}
// Usage — set CostCenter = '007' on a vendor record
VendTable vendTable;
select forUpdate vendTable
where vendTable.AccountNum == 'US-001';
ttsBegin;
vendTable.DefaultDimension = setDefaultDimensionValue(
vendTable.DefaultDimension,
'CostCenter',
'007');
vendTable.doUpdate();
ttsCommit;
Calling update() on a record inside a posting or integration pipeline triggers validateWrite() and modifiedField() which can cascade into unwanted side effects. Use doUpdate() when you are writing dimension values as a targeted field update, not as a full record edit.
The DimensionAttributeValue::findByDimensionAttributeAndValue() call with false, true parameters looks up an existing value and throws if it is not found. If you are writing a dimension value that may not exist yet (e.g. in a data migration), use true, false to create it, but be aware this bypasses any setup validation on the dimension.
Part 3 — Merging default dimensions
Merging is how D365 F&O builds dimension sets when a document header copies to a line, or when an item's dimensions are combined with a purchase order line's dimensions. Understanding merge precedence is essential for building integrations that produce the same result as the standard application.
Merge precedence rule
When two default dimension sets are merged, the first parameter wins — values from _value1 take precedence over _value2. Empty values in _value1 are filled in from _value2.
// Verified API signature from Microsoft Learn
// public static DimensionDefault serviceMergeDefaultDimensions(
// DimensionDefault _value1, ← higher precedence
// DimensionDefault _value2, ← lower precedence (fills empty slots)
// DimensionDefault _value3 = 0,
// DimensionDefault _value4 = 0)
// Example: merge header dimensions with line dimensions
// Header has higher precedence — same as standard PurchLine logic
DimensionDefault mergedDim = DimensionDefaultFacade::serviceMergeDefaultDimensions(
purchLine.DefaultDimension, // line (higher — user can override)
purchTable.DefaultDimension); // header (lower — fills gaps)
// If you need to merge more than 4 sources, chain the calls:
DimensionDefault step1 = DimensionDefaultFacade::serviceMergeDefaultDimensions(
source1, source2);
DimensionDefault step2 = DimensionDefaultFacade::serviceMergeDefaultDimensions(
step1, source3);
DimensionDefault finalDim = DimensionDefaultFacade::serviceMergeDefaultDimensions(
step2, source4);
Replace a single attribute value in a merged set
Use serviceReplaceAttributeValue() when you want to overwrite exactly one dimension in an existing set without touching the others — for example, overriding the transaction type dimension from a posting parameter.
// public static DimensionDefault serviceReplaceAttributeValue(
// DimensionDefault _target,
// DimensionDefault _source,
// RecId _dimensionAttributeId)
// Replace the Department dimension in the target set with the value from a source set
DimensionAttribute deptAttribute = DimensionAttribute::findByName('Department');
DimensionDefault updatedDim = DimensionDefaultFacade::serviceReplaceAttributeValue(
targetDefaultDimension, // dimension set to update
sourceDepartmentDimension, // dimension set containing the new value
deptAttribute.RecId); // which attribute to replace
serviceMergeDefaultDimensions() merges without validating against the current ledger's account structures. serviceMergeValidDefaultDimensions() performs the same merge but filters out values that are not valid for the current company's ledger. Use the validated version when building the dimensions that will be posted to the GL — this prevents the "dimension value is not valid for this account structure" error at posting time.
Part 4 — Building ledger dimensions from scratch
A ledger dimension is a main account combined with dimension values, constrained by the company's account structure. You build one from two ingredients: a default account (main account) and a default dimension set.
API selection guide
Pattern 1 — Build a ledger dimension from a main account + default dimensions
// Step 1: Get the default account RecId from a main account number
// LedgerDefaultAccountHelper builds a minimal ledger dimension with no extra dimensions
LedgerDimensionAccount defaultAccount =
LedgerDefaultAccountHelper::getDefaultAccountFromMainAccountId('110180');
// Step 2: Get or build your default dimension set
// Here we take it from a vendor record
VendTable vendTable = VendTable::find('US-001');
DimensionDefault vendorDim = vendTable.DefaultDimension;
// Step 3: Create the ledger dimension — main account from defaultAccount,
// dimension values filled from vendorDim
// API: LedgerDimensionFacade::serviceCreateLedgerDimension(
// RecId _ledgerDimensionId, ← source of main account
// DimensionDefault _dimensionDefault1,
// DimensionDefault _dimensionDefault2 = 0,
// DimensionDefault _dimensionDefault3 = 0)
LedgerDimensionAccount ledgerDim =
LedgerDimensionFacade::serviceCreateLedgerDimension(
defaultAccount,
vendorDim);
// Use on a journal line
ledgerJournalTrans.LedgerDimension = ledgerDim;
Pattern 2 — Build a ledger dimension with a custom dimension override
This is the pattern when you need to combine the main account from a posting profile with dimension values from a transaction record, and override one specific dimension from a parameter.
public static LedgerDimensionAccount buildLedgerDimWithOverride(
MainAccountNum _mainAccount,
DimensionDefault _transactionDimensions,
Name _overrideDimName,
DimensionValue _overrideDimValue)
{
LedgerDimensionAccount defaultAccount;
DimensionDefault overrideDim;
DimensionDefault mergedDim;
// Build the base account from main account number
defaultAccount = LedgerDefaultAccountHelper::getDefaultAccountFromMainAccountId(_mainAccount);
// Build a temporary default dimension set with just the override value
DimensionAttributeValueSetStorage dimStorage = DimensionAttributeValueSetStorage::find(0);
DimensionAttribute dimAttribute = DimensionAttribute::findByName(_overrideDimName);
DimensionAttributeValue dimValue = DimensionAttributeValue::findByDimensionAttributeAndValue(
dimAttribute, _overrideDimValue, false, true);
dimStorage.addItem(dimValue);
overrideDim = dimStorage.save();
// Merge: override has higher precedence than transaction dimensions
mergedDim = DimensionDefaultFacade::serviceMergeDefaultDimensions(
overrideDim, // higher precedence — our override wins
_transactionDimensions); // lower precedence — fills remaining gaps
// Build the final ledger dimension
return LedgerDimensionFacade::serviceCreateLedgerDimension(
defaultAccount,
mergedDim);
}
// Usage: post to account 618900 using the PO line dimensions,
// but override the Department to '099' (a custom posting rule)
LedgerDimensionAccount finalLedgerDim = buildLedgerDimWithOverride(
'618900',
purchLine.DefaultDimension,
'Department',
'099');
ledgerJournalTrans.LedgerDimension = finalLedgerDim;
Pattern 3 — Copy a ledger dimension from a posted transaction to a new document
When reversing or correcting a posted transaction, never copy the LedgerDimension RecId directly. Account structures may have changed since the original post. Use serviceCreateLedgerDimFromLedgerDim() to rebuild the combination against the current structure.
// WRONG — copies the RecId directly, may fail posting validation
// if account structure has changed since original post
newJournalTrans.LedgerDimension = originalJournalTrans.LedgerDimension;
// CORRECT — rebuilds the combination against the current account structure
newJournalTrans.LedgerDimension =
LedgerDimensionFacade::serviceCreateLedgerDimFromLedgerDim(
originalJournalTrans.LedgerDimension);Part 5 — Replacing a dimension value on an existing ledger dimension
A common integration requirement: given an existing LedgerDimension on a journal line, replace one dimension value without changing the main account or any other dimension. For example, replacing the Business Unit from a transaction type parameter at posting time.
public static LedgerDimensionAccount replaceDimOnLedgerDim(
LedgerDimensionAccount _existingLedgerDim,
Name _dimensionAttributeName,
DimensionValue _newValue)
{
// Step 1: Extract the main account and default dimensions from the existing ledger dim
RecId mainAccountRecId = LedgerDimensionFacade::getMainAccountRecIdFromLedgerDimension(_existingLedgerDim);
DimensionDefault existingDimDefault = LedgerDimensionFacade::getDefaultDimensionFromLedgerDimension(_existingLedgerDim);
// Step 2: Build a single-value default dim with the new value
DimensionAttribute dimAttribute = DimensionAttribute::findByName(_dimensionAttributeName);
DimensionAttributeValue dimValue = DimensionAttributeValue::findByDimensionAttributeAndValue(
dimAttribute, _newValue, false, true);
DimensionAttributeValueSetStorage dimStorage = DimensionAttributeValueSetStorage::find(0);
dimStorage.addItem(dimValue);
DimensionDefault newSingleDim = dimStorage.save();
// Step 3: Replace the specific attribute in the existing set
DimensionDefault updatedDimDefault = DimensionDefaultFacade::serviceReplaceAttributeValue(
existingDimDefault, // target
newSingleDim, // source of the new value
dimAttribute.RecId); // which attribute to replace
// Step 4: Rebuild the ledger dimension with updated dimensions
LedgerDimensionAccount defaultAccount =
LedgerDefaultAccountHelper::getDefaultAccountFromMainAccountRecId(mainAccountRecId);
return LedgerDimensionFacade::serviceCreateLedgerDimension(
defaultAccount,
updatedDimDefault);
}
// Usage: replace Business Unit on an existing journal line ledger dimension
ledgerJournalTrans.LedgerDimension = replaceDimOnLedgerDim(
ledgerJournalTrans.LedgerDimension,
'BusinessUnit',
'OU_004');Part 6 — A reusable dimension helper class
Rather than repeating the DimensionAttribute::findByName() call everywhere, a centralised helper class that names each dimension attribute as a static method makes your code cleaner, enables Find All References in Visual Studio, and avoids magic strings scattered across the codebase.
///
/// Central helper for financial dimension operations.
/// Add a static method for each dimension attribute used in your customisation.
///
public class CSTDimensionHelper
{
// -------------------------------------------------------
// Dimension attribute name constants
// -------------------------------------------------------
private static Name BusinessUnit() { return 'BusinessUnit'; }
private static Name CostCenter() { return 'CostCenter'; }
private static Name Department() { return 'Department'; }
private static Name Project() { return 'Project'; }
// Add your custom dimensions here — one method per dimension
// private static Name TransactionType() { return 'TransactionType'; }
// -------------------------------------------------------
// Read a value from a default dimension set
// -------------------------------------------------------
public static DimensionValue getValueFromDefaultDim(
DimensionDefault _defaultDimension,
Name _dimensionName)
{
DimensionAttributeValueSetItemView dimView;
DimensionAttribute dimAttribute;
select firstonly DisplayValue from dimView
where dimView.DimensionAttributeValueSet == _defaultDimension
exists join dimAttribute
where dimAttribute.RecId == dimView.DimensionAttribute
&& dimAttribute.Name == _dimensionName;
return dimView.DisplayValue;
}
// -------------------------------------------------------
// Set a single value on a default dimension set
// Returns new DefaultDimension RecId
// -------------------------------------------------------
public static DimensionDefault setValueOnDefaultDim(
DimensionDefault _existingDim,
Name _dimensionName,
DimensionValue _value)
{
DimensionAttributeValueSetStorage dimStorage;
DimensionAttribute dimAttribute;
DimensionAttributeValue dimAttributeValue;
dimStorage = DimensionAttributeValueSetStorage::find(_existingDim);
dimAttribute = DimensionAttribute::findByName(_dimensionName);
if (_value)
{
dimAttributeValue = DimensionAttributeValue::findByDimensionAttributeAndValue(
dimAttribute, _value, false, true);
dimStorage.addItem(dimAttributeValue);
}
else
{
dimStorage.removeDimensionAttribute(dimAttribute.RecId);
}
return dimStorage.save();
}
// -------------------------------------------------------
// Convenience accessors — named per dimension
// -------------------------------------------------------
public static DimensionValue getCostCenter(DimensionDefault _defaultDim)
{
return CSTDimensionHelper::getValueFromDefaultDim(_defaultDim, CSTDimensionHelper::CostCenter());
}
public static DimensionDefault setCostCenter(DimensionDefault _defaultDim, DimensionValue _value)
{
return CSTDimensionHelper::setValueOnDefaultDim(_defaultDim, CSTDimensionHelper::CostCenter(), _value);
}
public static DimensionValue getDepartment(DimensionDefault _defaultDim)
{
return CSTDimensionHelper::getValueFromDefaultDim(_defaultDim, CSTDimensionHelper::Department());
}
public static DimensionDefault setDepartment(DimensionDefault _defaultDim, DimensionValue _value)
{
return CSTDimensionHelper::setValueOnDefaultDim(_defaultDim, CSTDimensionHelper::Department(), _value);
}
// -------------------------------------------------------
// Build a ledger dimension from a main account + default dim
// -------------------------------------------------------
public static LedgerDimensionAccount buildLedgerDimension(
MainAccountNum _mainAccountNum,
DimensionDefault _defaultDimension)
{
LedgerDimensionAccount defaultAccount =
LedgerDefaultAccountHelper::getDefaultAccountFromMainAccountId(_mainAccountNum);
return LedgerDimensionFacade::serviceCreateLedgerDimension(
defaultAccount,
_defaultDimension);
}
}
// Usage — clean, readable, refactor-safe
VendTable vendTable = VendTable::find('US-001');
str costCentre = CSTDimensionHelper::getCostCenter(vendTable.DefaultDimension);
str department = CSTDimensionHelper::getDepartment(vendTable.DefaultDimension);
// Set a new cost centre
ttsBegin;
vendTable.reread();
vendTable.DefaultDimension = CSTDimensionHelper::setCostCenter(
vendTable.DefaultDimension, '009');
vendTable.doUpdate();
ttsCommit;
// Build a ledger dimension for a journal line
ledgerJournalTrans.LedgerDimension = CSTDimensionHelper::buildLedgerDimension(
'110180',
custTable.DefaultDimension);Common pitfalls summary
LedgerJournalTrans.LedgerDimension is a RecId, not a string. Assigning an account number string assigns 0 to a numeric field — the compiler does not catch this. The journal line posts with an unresolved account. Always use LedgerDefaultAccountHelper::getDefaultAccountFromMainAccountId() to build the RecId.
If the account structure configuration has changed since the original document was posted, copying the RecId directly may produce a ledger dimension that fails posting validation. Always use LedgerDimensionFacade::serviceCreateLedgerDimFromLedgerDim() when copying from a historic document to a new one.
In serviceMergeDefaultDimensions(_value1, _value2), _value1 has higher precedence. Many developers assume the second parameter wins. The rule is: _value1 values always win; _value2 only fills in empty slots. Getting this backwards causes dimensions from the wrong source to appear on posted transactions.
If you want to overwrite one specific dimension in an existing set, use serviceReplaceAttributeValue(). Using serviceMergeDefaultDimensions() will also copy any other non-empty values from the source set, which is usually not what you want when overriding a single attribute.
If a main account has a dimension set as Fixed in the Main Accounts setup (General Ledger → Chart of Accounts → Main accounts → Legal entity overrides → Default dimensions), that value overwrites whatever your code sets at posting time — even if the user manually entered a different value. If dimension values are disappearing or changing after posting, check Fixed dimension configuration on the main account before looking at the code.
Conclusion :-
The Financial Dimension Framework has a steep initial learning curve because it hides significant complexity behind what looks like a simple field on a record. Once you understand that every dimension field is a RecId into an immutable normalised set, and that there are specific facade APIs for every operation — reading, writing, merging, and building ledger dimensions — the framework becomes predictable and systematic.
The four classes you need to know for 95% of dimension work are: DimensionAttributeValueSetStorage for reading and writing default dimensions, DimensionDefaultFacade for merging and replacing values, LedgerDimensionFacade for all ledger dimension operations, and LedgerDefaultAccountHelper for building default accounts from main account numbers.
Building a centralised helper class with named methods for each dimension attribute in your project — as shown in Part 6 — removes magic strings from the codebase, makes dimension logic refactorable, and produces code that any developer on the project can read and maintain.
