Concluding this series of blog posts, this section covers additional defaulting patterns and APIs that can be used in advanced scenarios.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage
• Copy patterns
• Merging patterns
• Ledger dimension creation
• Common pattern APIs
• Advanced topics (this post)

DimensionDefaultingEngine

In the previous blog post, the DimensionDefaultingService class was described. It provides the common APIs needed for most defaulting needs. For scenarios not supported by the DimensionDefaultingService, the DimensionDefaultingEngine class can be used directly. This class provides all of the logic for the DimensionDefaultingService class.

The engine leverages a concept called dimension specifiers which is a map of dimensions and values obtained from default dimensions and ledger dimensions. The documentation for the DimensionDefaultingEngine can be found on MSDN.

Defaulting during segment entry

In most cases, the merging of default dimensions to a ledger dimension occurs before the user has begun editing the ledger account combination in a segmented entry control. In some circumstances, the form has logic to perform defaulting as the user enters each segment in the control. In order to do this, the form must respond to events raised by the segmented entry control.

To perform defaulting at entry leveraging the DimensionDefaultingEngine class, the segmentValueChanged() method on the segmented entry control is overridden. Defaulting can then be based on current values in the control providing values for other segments.  This example in Figure 1 adds dimension values from the MainAccount table, merging with other values, as soon as a MainAccount is entered in the segmented entry control.

Figure 1: Sample segmentValueChanged() override to default during segment entry

This concludes this series of blog posts about dimension defaulting.

Continuing this series of blog posts, this post describes APIs used for most common defaulting patterns.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage
• Copy patterns
• Merging patterns
• Ledger dimension creation
• Common pattern APIs (this post)
• Advanced topics

DimensionDefaultingService APIs

The dimension defaulting service provides the APIs needed for defaulting scenarios. The methods are highly optimized for performance.

Default dimensions

The serviceMergeDefaultDimensions() API is the most commonly used API for default dimensions. It should be called whenever a new default dimension needs to be created from 2 to 4 other default dimensions. If more default dimensions need to be merged than 4, it can be called multiple times with the result of the prior call used as the first parameter to the subsequent call.

Figure 1: DimensionDefaultingService.serviceMergeDefaultDimensions()

The serviceReplaceAttributeValue() API is useful in the case that a single dimension value needs to be copied from one default to another default set. The value specified will replace whatever value already exists in the source set.

Figure 2: DimensionDefaultingService.serviceReplaceAttributeValue() 

Ledger dimensions

The serviceCreateLedgerDimension() API is the most commonly used API for ledger dimensions. It should be called whenever a new ledger account combination needs to be created from a default account or existing ledger account combination and 0 to 3 default dimensions. If more default dimensions need to be merged than 3, it can be called multiple times with different sources taking the result of the prior call as the first parameter to the subsequent call. The MainAccount dimension is only retrieved from the supplied ledger dimension.

Figure 3: DimensionDefaultingService.serviceCreateLedgerDimension()

The serviceCreateLedgerDimensionForType() API is similar to the previous API but rather than creating a ledger account combination, it can create other ledger dimension types such as budget accounts or budget planning accounts specified by the LedgerDimensionType parameter.

Figure 4: DimensionDefaultingService. serviceCreateLedgerDimensionForType()

The serviceCreateLedgerDimForDefaultDim() API is similar to the previous APIs, but the values from the default dimension are copied directly to the new ledger dimension, while the dimension values from the ledger dimension are merged afterwards. In the previous APIs, the ledger dimension values were copied, and the default dimension values were merged.

Figure 5: DimensionDefaultingService.serviceCreateLedgerDimForDefaultDim()

The serviceLedgerDimensionFromLedgerDims() API is similar to the previous APIs but uses only ledger dimensions as sources to construct a new ledger dimension. The main account will only be retrieved from the first ledger dimension.

Figure 6: DimensionDefaultingService.serviceLedgerDimensionFromLedgerDims()

The serviceMergeLedgerDimensions() API is similar to the previous API but is optimized to combine just 2 ledger dimensions. 

Figure 7: DimensionDefaultingService.serviceMergeLedgerDimensions()

The serviceCreateLedgerDimFromLedgerDim() API is useful when copying ledger dimensions from a historic posted document onto a new unposted document to ensure that it uses the current account structure configuration.  This will avoid validation errors when validating the new ledger dimensions during posting.

Figure 8: DimensionDefaultingService.serviceCreateLedgerDimFromLedgerDim()

In the next blog post, additional defaulting patterns and APIs that can be used in advanced scenarios will be described.

Continuing this series of blog posts, this post covers how default dimensions can be merged to create new ledger dimensions.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage
• Copy patterns
• Merging patterns
• Ledger dimension creation (this post)
• Common pattern APIs
• Advanced topics

Ledger dimension creation

Default dimensions exist as a way to provide values that later will be used to create ledger account combinations used in journals and accounting distributions. Default dimensions provide the dimensions other than MainAccount needed for a ledger account combination, and can be combined with a default account, or another ledger dimension in order to produce one.  As defined in the Ledger account combinations series of blog posts, a ledger account combination is just a set of MainAccount and dimension values with structure and order applied.

Figure 1: Accounting distributions from the purchase order line

As shown in Figure 1 above, choosing the Financials->Distribute amounts option from the purchase order line the accounting distributions form opens. It already has a ledger account combination defaulted “604250-00000001--Chicago-00000004”. From the previous blog post, the values for the Project, BusinessUnit and Department dimensions have been populated and a MainAccount defaulted from the posting item group on the item, as the Purchase expenditure for expense account for a purchase order as shown in Figure 2 below.

Figure 2: Source of a default (main) account for the item on the purchase order line

Figure 3: SQL query and results showing default account source

The code required to merge the default dimension on the purchase order line with the default account from the item group is shown in Figure 4 below. 

Figure 4: Code used to merge the default dimension with a default account

Similar to merging default dimensions, once merged, a newledger account combination is created as shown in the query in Figure 5 below:

Figure 5: SQL query and results showing merged default account and default dimension

In the next blog post, APIs used for most common defaulting pattern APIs will be described.

Continuing this series of blog posts, this post covers how default dimensions are merged between entities.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage
• Copy patterns
• Merging patterns (this post)
• Ledger dimension creation
• Common pattern APIs
• Advanced topics

Default dimension merging

Figure 1 below shows the user manually cleared the Department dimension on the line, which in turn creates a new default dimension foreign key and updates the purchase order line.  Since the line has not yet been saved this updated foreign key is only visible on the table buffer in memory, but the new default dimension can be queried and found as shown in Figure 2 below. 

Figure 1: Default dimension modified on a document line (Purchase order line)

Figure 2: SQL query and output showing updated default dimensions

Next, consider the item that the user will enter on the purchase order line.  Figures 3 and 4 below show default financial dimensions on the released product and the SQL query and result for that default dimension in the database.

Figure 3: Default dimensions on an item

Figure 4: SQL query and output showing default dimensions on item record

Next, the user enters the item on the purchase order line.  Figures 5 below shows the item selected on the purchase order line and the resulting default dimensions. In this case, the default dimension values were merged by the purchase order logic.

Figure 5: Resulting default dimensions on a purchase order line

Figure 6: SQL query and output showing default dimensions on item record

The purchase order logic merges the default dimensions from 3 different sources when the item is specified for a purchase order line as shown in Figure 7 below.

Order header default dimensions merged with the order line default dimensions = merged result 1 default dimensions

Item default dimensions merged with merged result 1 = final order line default dimensions (merged result 2)

Figure 7: Merging steps taken

The tables in Figure 7 show the logical steps of  the merging that is occurring.  However, these steps are combined during execution using the APIs provided by the dimensions framework. Figure 8 below shows the code needed to do all of the merging of the dimensions from the 3 sources shown above.

Figure 8: Code used to merge the three sets of default dimensions

In the next blog post, examples of merging for the purpose of creating new ledger dimensions will be explained.

Continuing this series of blog posts, this section covers
how default dimensions are copied between entities.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage
• Copy patterns (this post)
• Merging patterns
• Ledger dimension creation
• Common pattern APIs
• Advanced topics

Copy versus merge

As initially described in the Dimension defaulting in accounting distributions series of blog posts, default dimensions are typically copied or merged with other dimension combinations to create ledger account dimensions. The dimension framework does not set the precedence for defaulting.  Each form or process determines this based on their business logic needs.

A hypothetical order document will serve as the basis for the examples below. This could be a service order interacting with customers and containing line item services, or a purchase order interacting with vendors and line item inventory items. In terms of where default dimensions are entered, they could be entered or overridden at different points in processing as shown in Figure 1 below.

Figure 1: Default dimension sources on a typical document

In the example of an order document, there are multiple default dimensions that are available for the business logic to consider. The document header may have a set of default dimensions like the purchase order in this example.  The customer or vendor of the order, such as the vendor in this case, has a set of default dimensions as well.  Depending on the business logic of the order, these different sets of default dimensions may have different precedence when combined together.  Some may have higher precedence and replace other default dimensions while others may be merged together.

Default dimension copy

Figure 2 below shows a default dimension entered on a specific vendor account. Figure 3 below shows the SQL query for the default dimension reference on the vendor record and the resulting default dimension created.

Figure 2: Default dimensions entered on a vendor account 

Figure 3: SQL query and output showing default dimensions on vendor record

Figures 4 and 5 below shows a new purchase order created for this vendor and the SQL query and default dimension reference on the header record. In this case the dimensions from the vendor replaced any dimensions already on the purchase order header as soon as a vendor is selected, so a direct copy of the default dimension foreign key was all that needed to be done as shown in Figure 6.

Figure 4: Default dimension copied to a document header (Purchase order) 

Figure 5: SQL query and output showing default dimensions on purchase order record

Figure 6: Code used to copy default dimensions from the vendor to the purchase order

Next, suppose the user enters a value for the Project dimension.  Figure 7 below, shows the header dimensions after that change. Figure 8 shows the SQL query for the default dimension reference on the header record and the resulting default dimension created.

Figure 7: Default dimension modified by a user on a document header (Purchase order)

Figure 8: SQL query and output showing updated default dimensions on purchase order record

Next, as the user changes to the Line view to enter the lines, Figures 9 and 10 below show default dimensions copied from the purchase order header and the code copying the foreign key reference to the line. In this case, the line has not yet been saved so the default dimension foreign key only appears in the table buffer in memory. 

Figure 9: Default dimension copied to a document line (Purchase order line)

Figure 10: Code used to copy default dimensions from the header to the line

This example will be continued in the next blog post where a line with an item is added to this purchase order, where dimensions will be merged instead of copied.

Continuing this series of blog posts, this post covers how default dimensions can be added to a form to display and allow entry by the user.

This blog post series includes:

• Financial dimensions discovery
• Control uptake and storage (this post)
• Copy patterns
• Merging patterns
• Ledger dimension creation
• Common pattern APIs
• Advanced topics

Form uptake and dimensions data model

All forms displaying default dimensions use the DimensionDefaultingController. The controller automatically handles displaying dimensions, loading and saving values and user interaction. These uptake patterns are documented in the Accounts and Dimensions whitepaper.

For more in depth details on the entire dimensions data model, refer to the previous blog post series on the dimension framework: Ledger account combinations - Part 2 (Dimension enumerations, default dimensions)

Default dimension value storage

The values associated with the dimensions are stored in a separate table apart from the primary table referencing them. For example, the LedgerJournalTable has a DimensionDefault column that holds a foreign key reference to a record in the DimensionAttributeValueSet table. This is the parent record representing the set of values displayed. Each individual value is stored as a separate row in the DimensionAttributeValueSetItem table sharing the same parent record foreign key. This data can be queried directly through these tables or using the DimensionAttributeValueSetItemView as shown in Figure 1 below.

 
 Figure 1: SQL query and (column trimmed) output for all default dimension values in one set

The output shown in Figure 1 above matches the 3 entered values in the previous blog post, shown here as Figure 2 below.

Figure 2: Default dimension entry

Empty values

As shown in Figure 1 above, the dimension framework only stores rows for dimensions that have a value entered. No data is stored for empty rows. Therefore, once persisted, the framework does not have the ability to determine the difference between a dimension that did not have a value and one that had a value but was cleared out by a user. In order to save an empty value, a real value must be created with a name indicating it is empty such as “empty”, “n/a”, “<cleared>”, “_blank_”. The user can then select this value at entry time to impact defaulting behavior as desired.

Immutable data

As with most all dimension data, the records that are inserted into the tables above are immutable. They are only written initially and never subsequently updated or deleted. In Figure 3, when the user adds a Project ID and then saves, the query above in Figure 1 will still return the same three rows. The dimension framework has created a new value set record and 4 additional value set item records linking to the new value set as shown in Figure 4 below.

Figure 3: Default dimension entry of one added value

Figure 4: SQL query and (column trimmed) output for all default dimension values the new set

In the next blog post, examples of defaulting copy patterns will be explained.

This series of blog posts describes default dimensions, starting from where the dimensions originate, the APIs used to merge them, and how they are used to create a ledger dimension. Examples showing the user interface as well as SQL table queries with output are included along with some explanation of APIs and usage examples.

This blog post series includes:

• Financial dimensions discovery (this post)
• Control uptake and storage
• Copy patterns
• Merging patterns
• Ledger dimension creation
• Common pattern APIs
• Advanced topics

Default dimension entry

There are approximately 250 forms in the SYS layer for Microsoft Dynamics AX 2012 R3 that allow the entry of default financial dimensions. They appear in their own tab page or fast tab and display a list of dimensions with values and descriptions as shown in Figure 1 below.

Figure 1: Default dimension entry

In standard demo data, as seen in Figure 2 below, there are over 20 dimensions listed but only 5 are shown in the example in Figure 1 above. How is the list filtered down?

Figure 2: Financial dimension list

The list is determined by starting with the the current company or a specific company specified on a form. The company context is used to obtain a list of all active account structures associated with its ledger. Finally, a union of all of the dimensions in these account structures, plus all active advanced rules associated with those structures is obtained.

In this example, the demo data company being used is “SUSB”. Opening the Ledger form (General Ledger->Setup->Ledger), it shows that two different account structures are used by this company as shown in Figure 3 below.

Figure 3: Ledger configuration for company “SUSB”

Selecting the first account structure and clicking the Configure account structure button shows 3 dimensions are used by that account structure as shown in Figure 4 below. Selecting the second account structure shows 5 dimensions are used in that account structure as shown in Figure 5 below.

Figure 4: Balance sheet account structure setup for company “SUSB”

Figure 5: Profit and loss account structure setup for company “SUSB”

Comparing the dimensions from both account structures, there are a total of 5 unique dimensions.  Four of these dimensions account for dimensions displaying in the default dimensions. In addition to these dimensions, dimensions from advanced rule structures linked to those account structures through advanced rules are also examined.  In this example, it results in a fifth dimension added to the default entry, LicensePlate.

It is also important to note that the MainAccount dimension is not shown in most default dimension lists. The exception to this is budgeting which does explicitly include the MainAccount as part of the list of default dimensions.

Figures 6 and 7 below show the advanced rule and structure resulting in the license plate dimension being display in the default dimensions. *Note: This was added specifically for this example and does not exist in standard demo data.

Figure 6: Advanced rule linked to the balance sheet structure

Figure 7:  The rule structure for LicensePlate

API for default dimensions list

The default dimension controller determines which dimensions are applicable for a company using the DimensionCache::getDimensionAttributeSetForLedger() API.  

In the next blog post, the hook-up to allow entry of default dimensions on a form and the storage used behind the control will be explained.

The DSB rebuild needs to be run if the detailed GL data is deleted or modified by any customization or other means outside of the core AX application. This includes jobs and using SQL directly.

Only invoke the DSB rebuild exactly once after all deleting and modifying of the detailed GL data is complete. Invoking the DSB rebuild more than once for the same change is unnecessary and can result in temporary degradation in performance.

To perform a DSB rebuild you can call DimensionFocusInitializeBalance::scheduleProcessFullRebuild(). This will schedule a batch job to rebuild balances. Pass in Ledger::current() if the detailed GL data that was deleted or modified was limited to the current company/ledger. Don’t pass a ledger parameter value if the detailed GL data that was deleted or modified was in multiple companies/ledgers. It is a normal AX practice to perform updates to a single company/ledger at a time.

Here is an example of a form close method which would be a logical place to do a DSB rebuild if updates came from the form. It is important to note that just closing the form with no changes should not invoke the full DSB rebuild.

private void close()
{

    if (changesMade)
    {

          DimensionFocusInitializeBalance::scheduleProcessFullRebuild(Ledger::current());
    }

}

The paper can be downloaded at: https://www.microsoft.com/en-us/download/details.aspx?id=41645

The below screenshot shows accounting distributions for a purchase order for a procurement category Workplace services. The accounting distribution for extended price has been split into 2 distributions. The line default value 00000024 for Department has been modified from 00000024 to 00000026 on line 1 and from 00000022 to 00000025 on line 2.  

Image 001 - PO Accounting distributions procurement category split

When the product receipt is created from this purchase order the accounting distributions for the receipt line will be split in the same ratio as the purchase order and will have the same dimension values as the purchase order distributions. In the below shown example in Image 002 the product receipt triggers a different main account (211250) which requires an additional dimension for Purpose. The value for Purpose (Site1) has been defaulted from the purchase order line default dimensions.

Image 002 - Accounting distributions for the product receipt