Dynamics AX GFM Team Blog

Ledger account combinations - Part 6 (Ledger dimensions (B))

Bill Frandsen — Fri, 15 Feb 2013 15:55:00 GMT

Introduction

Continuing this series of blog posts, we continue the discussion on the LedgerDimensions region highlighted in pale yellow in the model below in figure 1.

Figure 1: Ledger dimension storage in framework

Ledger dimension storage with rules

Building on the ledger dimension storage example started in the previous blog post, we will add to the scenario and assume the user will go back and change the values from [ 150 - A ] to [ 145 - Q ]. As we know from the advanced rules previously set up, this will trigger a third segment to be added to the account structure.

Figure 2: In-edit ledger account segment (before tab)

When the user tabs from the second segment, a third segment is added to the control and focus placed in it:

Figure 3: In-edit ledger account segment (after tab)

Now, the user can enter a license number:

Figure 4: Completed ledger account field

As soon as the third field is entered and the user tabs out of the control, it will trigger the validation of the combination. If it is valid, the combination will be saved as a LedgerDimension.

The following is known about the new combination:

The account structure is "MyAccountStructure"
The first segment is the "MainAccount" dimension with a value of 145.
The second segment is the "Customer" dimension with a value of Q.
1 additional segment was added due to an account rule structure "MyRuleStructure1" being added due to the values matching the rule for the first two segments.
The third segment is the "LicensePlate" dimension with a value of AAA 111.

Figure 5: Ledger dimension storage query results

For this combination, a total of 8 rows were inserted across the 4 tables storing the ledger dimension. The difference between the first ledger account combination, discussed in the previous post, and this one is that multiple structures are being used to drive the dimensions that make up the ledger account combination. There are 2 records stored in the DimensionAttributeValueGroupCombination and DimensionAttributeValueGroup tables, each one representing a structure used and joined to the full combination.

Notice that each record has a new RecID assigned to it. The combination of the previous values is not updated, but rather a new combination is created making the LedgerDimensions immutable. This was done because there is no reference counting maintained on the use of the combination. The same [ 150 - Q ] combination originally entered may have been referenced from multiple tables within the application before the user decided to change an instance to [ 145 - Q - AAA 111]. Therefore, a new combination must be created and the reference changed to it only from the table that the ledger account combination is being changed on.

Because a user may change the combination on a record by adding or removing segment values and a new LedgerDimension created, it is possible to end up with unreferenced or orphaned LedgerDimensions over time. Allowing orphaned combinations improves performance of the overall dimension framework to not issue deletes across the tables in question when combination is changed. It is also likely after a combination is used once that it will be reused again and removing it instantly on removal of the last reference may only result it in being recreated again. Orphaned LedgerDimensions are still structurally valid and can be reused in the future if the combination of values in relation to the structures and rules are entered again. If a combination is ever entered a subsequent time, no records are inserted and the existing reference is reused providing greater performance.

Optimizations are also made for storage size and insert cost when advanced rules are used. Consider the following example as a new account combination is entered:

Figure 6: Changed ledger account field

In this case, the only difference between the new combination and the previous is that the license plate number (provided by the advanced rule) was changed. The data storage of the combination will appear as follows (new records in white):

Figure 7: Additional ledger dimension storage query results

In the creation of the new combination, the 5 records highlighted in white were inserted:

1 in DimensionAttributeValueCombination
2 in DimensionAttributeValueGroupCombination
1 in DimensionAttributeValueGroup (instead of 2)
1 in DimensionAttributeLevelValue (instead of 3)

This is because the values stored as part of the account structure 'group' are the same between the previous combination (DAVC2) and this combination (DAVC3). Those DimensionAttributeValueGroup and DimensionAttributeLevelValue records did not need to be recreated. Instead, we were able to reuse 3 records and save their insertion cost.

Alternately, had the structure associated with the account rule allowed blanks for the license plate number, and a combination of just [ 145 - Q ] was created, there would only have been 2 new records inserted instead:

1 in DimensionAttributeValueCombination
1 in DimensionAttributeValueGroupCombination
0 in DimensionAttributeValueGroup
0 in DimensionAttributeLevelValue

This is because all of the DimensionAttributeValueGroup and DimensionAttributeLevelValue records already existed and could be fully reused on the new combination. This is the primary reason why data should never be directly modified within the LedgerDimension storage tables. A change to a single record could affect not only all references to that ledger dimension but also one or more other ledger dimensions and references to them.

Although partially collapsed in the above examples in figure 5 and figure 7, there is a Hash code assigned to the DimensionAttributeValueCombination and DimensionAttributeValueGroup tables. The purpose and source of this advanced data column are discussed in the next and final blog post in this series.

Ledger account combinations - Part 7 (Advanced topics)

Bill Frandsen — Fri, 15 Feb 2013 15:55:00 GMT

Introduction

Concluding this series of blog posts, we will discuss some of the advanced topics that explain some of the deeper design and implementation decisions that drive the way the dimension framework works.

The model below in figure 1 shows the various areas within the dimension framework.

Figure 1: Overall framework

Hashes

The design of the database storage in the dimension framework intends to:

Support immutable data where data is only inserted, never updated or deleted
Reuse previously created combinations to lower insertion costs
Avoid reference counting and maintenance of it
Provide fast performance to find an existing combination for reuse

As the dimension framework allows unlimited dimensions and unlimited structures on a ledger account combination, it is difficult to create a single large or multiple smaller queries to find an existing set or combination. Since the number of records and order of those records is potentially different for every combination, a hash-based solution was implemented.

This hash represents the unique information contained in the associated tables' records for fast querying. A single binary container field (160 bit, 20 byte hash column) is stored to uniquely identify the data contained by the set or combination.

The dimension framework uses hashes to uniquely identify data in the following tables:

DimensionAttributeValueCombination

Consisting of data from all the linked records in the DimensionAttributeValueGroup and DimensionAttributeLevelValue tables

DimensionAttributeValueGroup

Consisting of data from the linked records in the DimensionAttributeLevelValue table

DimensionAttributeSet

Consisting of data from the associated DimensionAttributeSetItem records

DimensionAttributeValueSet

Consisting of data from the associated DimensionAttributeValueSetItem records

Hash messages

In order to produce a hash, a message is created containing individual ordered information about the contents of the set or combination. It varies based upon the particular hash being generated, but basically includes information about the dimensions, values, and structures and their order within the set or combination, if applicable. This information is internally calculated in a prescribed manner and passed onto a hashing routine to generate a SHA-1 hash to persist using a binary container. The exact order and contents of these messages are provided by the methods within the storage supporting classes of the dimension framework including the DimensionAttributeSetStorage, DimensionAttributeValueSetStorage, and DimensionStorage classes.

HashKeys

In order to generate a hash message, something that uniquely identifies each dimension, value and structure that makes up the combination is needed. While a RecID can serve as a unique identifier, it is only considered a surrogate, as it is not immutable and can change if the record were to be exported and imported into a different system or partition, for example. The RecID can be reassigned during the import process. Any hash that was created with a hash message using a RecID could no longer be used to identify a combination in the dimension framework for that new system or partition. Instead another identifier, a GUID, is used. This GUID resides on the DimensionAttribute, DimensionAttributeValue and DimensionHierarchy tables and is stored in the HashKey column. Each time a new record is created, a GUID is assigned and remains with that record to uniquely identify it.

Risks of changing data directly

It is extremely important that no data be directly modified outside of the application framework such as in SQL Server Management Studio. This extends to modifying any data in any column of the table not just the columns discussed in these posts; as well as replicating data from one row to another and attempting to create 'new' sets or combinations outside of the dimension framework storage classes.

It is also important to understand this when considering backups and only partial restoration of data which could affect referential and hash integrity. For example, it would be problematic to only back up the LedgerDimension related records and importing them into another partition without also bringing in all of the other records in the dimension framework as well as all of the backing entity records such as from the CustTable or others that were used in the creation of any combinations. Any attempts to modify the data in these tables or to synthesize GUIDs or hashes will lead to corrupt data and complex time consuming analysis to find the source of the corruption and to try to undo it.

Apparent duplicate combinations

When browsing the tables of the dimension framework, it may appear that combinations are duplicated when only viewing the DisplayValue field stored on the records. This does not mean that duplicate combinations exist; rather it means that data within the hash or joined tables is different even though the DisplayValue appears the same. The DisplayValue strings are stored on the records to improve performance for some scenarios but are not used to uniquely identify the record.

Consider an account structure with [ MainAccount - Department ] in one company and another account structure with [ MainAccount - CostCenter ] in a different company. It is possible for the DisplayValue of 2 combinations, one for each account structure, to appear as " 145 - A ". For the first account structure "A" represents a Department within that company, but for the second it represents a Cost center within that company. Additionally, there are multiple types of a LedgerDimension that are stored in the DimensionAttributeValueCombination table including special ones for budgeting that may appear the same from examining the DisplayValue field as other combinations ones but hold different information internally and hold uniquely different hash values.

Versioning / date effective data

The dimension framework does not support versioning or date effective data directly. If any backing entities it references are versioned, and a new RecID assigned to newer versions within the same table, the framework will properly link to the correct version through the DimensionAttributeValue record. If the same backing entity record is used and another table tracks revisions to it in the owning module, then the dimension framework will not be able to know the difference as the backing entity RecID would not be different between versions. None of the dimension framework tables (such as dimensions, structures, rules, constraints) internally support versioning. The previous versions are replaced with a new version with no history maintained.

When a structure or rule is changed, and there are ledger account combinations saved on unposted transactions, the dimension framework will create new combinations and update any foreign key references to them on unposted transaction tables. It will not change the original combinations as they may be referenced from posted transactions. The two combinations are not linked in any way. There is not a way to determine the way a structure and its rules appeared prior to change. Some information can be determined by the data stored in the combination, but since blank values are not stored, it is incomplete and cannot be used to reconstruct a previous version.

The dimension framework does supports valid from and valid to dates at the level of a dimension value. This indicates when the value is considered "valid" and does not represent the historical state of the value in the same way that date effective data does.

This concludes this series of blog posts about the dimension framework and “What happens when I create a ledger account combination?”

Ledger account combinations - Part 5 (Ledger dimensions (A))

Bill Frandsen — Fri, 15 Feb 2013 15:54:00 GMT

Introduction

Continuing this series of blog posts, we will cover the LedgerDimensions region highlighted in pale yellow in the model below in figure 1. This region will be discussed in two parts covering this post and the next post.

Once all of the configuration data is set up, ledger account combinations can be entered, validated and persisted. The primary consumption of the dimension framework occurs when the application leverages this area.

Figure 1: Ledger dimension storage in framework

Ledger dimension storage without rules

To understand LedgerDimensions, we need to understand how a ledger account combination is entered by a user.

Using the account structure and rule setup from the previous blog post (#4 - Advanced rules), we will walk through the user interaction with the account entry control when an account is entered. To refresh, the account structure appears as follows:

Figure 2: Basic structure and constraints

There is a single account rule associated with the structure:

Figure 3: Single rule added

With the added structure defined as follows:

Figure 4: Single structure added

When a user first sees a ledger account field on a form, it will appear as follows when focus is not in the field:

Figure 5: Empty ledger account field (without focus)

When the user clicks into the field, since the account structure has 2 segments, the following will appear:

Figure 6: In-edit ledger account field

The user then enters the combination of [ 150 - A ].

Figure 7: Completed ledger account field

As soon as the second segment is entered and the user tabs out of the control, the dimension framework saves the combination and then validates if the combination is valid based on the constraints. In this case, the combination is valid.

The following is known about the combination:

The account structure is "MyAccountStructure"
The first segment is the "MainAccount" dimension with a value of 150.
The second segment is the "Customer" dimension with a value of A.
No additional segments were added on as the values did not match any advanced rules associated with this account structure.

Therefore, the 2 segment values are stored as follows across the 4 tables:

Figure 8: Ledger dimension storage query results

The first table is named DimensionAttributeValueCombination as it stores a full multi-segment account combination along with some de-normalized information about the combination such as the concatenated segments as a single string, a foreign key (FK) reference to the Account structure, and a FK to the MainAccount (150) that was used.

Skipping the second table for now, the third table is named DimensionAttributeValueGroup. It has this name as it stores each related group of segments associated with each structure that is present in the combination. In this case, there is only one structure, the Account structure, so there is only one record here.

The fourth table, named DimensionAttributeLevelValue, stores the individual segment values for each segment within the associated group or structure. One record exists for each segment entered. When a segment is empty, no values are stored for it. Each record references the corresponding DimensionAttributeValue record. If an existing one is found it is referenced, or if one does not exist for the value, it is created. This is the data linking the DimensionAttribute to the real backing entity record. In this case, one is for the MainAccount record with an ID of 150, and one is for the CustTable record with an ID of A.

In order to link the group of the account structure values and the segment values to the main record in the DimensionAttributeValueCombination table, a record is inserted into the second table above in figure 8, DimensionAttributeValueGroupCombination.

In order to save a single segment in a new combination at least one record is inserted in each of these 4 tables. An additional record is inserted in the DimensionAttributeLevelValue table for each additional segment entered. Abstractly, these 4 tables are referred to as a LedgerDimension. A LedgerDimension is expressed as a FK that references the RecId in the DimensionAttributeValueCombination table.

The use of advanced rules plays a role in the number of records involved in these tables for a combination. This will be covered in the next blog post.

Ledger account combinations - Part 4 (Advanced rules)

Bill Frandsen — Fri, 15 Feb 2013 15:53:00 GMT

Introduction

Continuing this series of blog posts, we will cover the Advanced Rules region highlighted in pale yellow in the model below in figure 1.

While account structures and constraints allow the user to build very simple to very complex trees of valid combinations, sometimes the business requirements are to only show a dimension as a segment in an ledger account combination only at certain times rather than just constrain the valid values allowed showing it all the time. The use of advanced rules supports this requirement.

Figure 1: Advanced rules in framework

Advanced rules

Advanced rules can be added to an account structure and its constraints. While versatile, there are guidelines when they should and should not be used for best usability, performance and understanding:

Rules cannot replace the account structure. A structure must always exist with at least a main account segment.
Rules cannot add dimensions before other segments already in the account structure.
Rules should not be used to replace the use of constraints in the account structure for additional dimensions that are always required regardless of the main account.
Rules should not be used to replicate segments that already exist in the account structure or other rules
Any duplication will automatically join and use the most restrictive constraint.
The location of the duplicated segment will only appear in the first occurrence of it.

Setting up an advanced rule involves defining a filter that controls when additional segments are added to a ledger account combination, and then linking rule structures (similar to account structures) that specify the additional segments, their hierarchy order and any constraints between them to be added.

Assuming the following account structure is set up:

Figure 2: Basic structure and constraints

Let’s assume that a new advanced rule is needed to optionally add a segment (or segments) only if the user has entered main account 145 and customers G thru Q:

Figure 3: Advanced rule form

Once the rule is configured, a structure and constraint definition needs to be created to define what segments to add to the ledger account combination. This is done by creating a new rule structure, similar to how an account structure is created. These structures are not immediately bound to the rule, and as such can be shared across multiple rules if necessary.

Figure 4: Advanced rule structure form

After the structure is created, it is added onto the dimension rule, and the account structure along with the rule is then activated:

Figure 5: Added advanced rule structure to rule

The storage of this data uses some of the same tables as the storage of the account structures discussed in the previous post. The DimensionRule, DimensionRuleAppliedHierarchy and DimensionRuleCriteria tables hold the data specific to the definition of the rule and the link to the definition of the rule structures. The rest of the tables are shared with the account structure definition:

Figure 6: Combined structure, rule and all constraints query results

Examples of the effects of these rules, rule structures, segments and constraints on the entry of a ledger dimension account will be explained in the next blog post when we begin discussing entry of ledger account combinations and their storage.

Ledger account combinations - Part 2 (Dimension enumerations, default dimensions)

Bill Frandsen — Fri, 15 Feb 2013 15:52:00 GMT

Introduction

Continuing this series of blog posts, we will cover the Dimension Enumerations and Default Dimensions sections highlighted in pale yellow in the model in figure 1 below.

Dimension enumerations and default dimensions are two storage mechanisms to store a set of references to either dimensions or dimension values. These commonly are exposed on a Financial dimensions tab on master data forms such as Customers (CustTable) or Vendors (VendTable).

Figure 1: Sets in framework

Dimension Enumerations

A dimension enumeration is a set of references to existing dimensions that are persisted for later use. These dimensions have no particular ordering and no constraints on which dimensions appear within the set by the dimension framework. However, in most instances, the set is constrained by the consuming code to the set of dimensions available in the current ledger. A dimension enumeration is stored in the DimensionAttributeSet and DimensionAttributeSetItem tables.

The set specifies an enumeration type which is the enumNum() of the BaseEnum that represents the source of enumeration values to associate with each dimension. Therefore, this is a list of enumeration values as defined by the developer; not a list of user-entered values from backing entities. In Dynamics AX 2012 R2, an example of this is storage of a list of dimensions that are to be Fixed, labeled as Fixed value, or NotFixed, labeled as Not fixed, which are associated with each main account.

Figure 2: Dimension enumerations on a form

In the above example in figure 2, the enumeration DimensionFixed is used to constrain the list of values in the drop down list.

Figure 3: A dimension enumeration BaseEnum

The value entered represents one item with a "1" EnumValue (DimensionFixed::Fixed) and the other one with the default "0" EnumValue (DimensionFixed::NotFixed). The DimensionAttributeSet is stored as follows:

Figure 4: Dimension enumeration storage query results

The MainAccountLegalEntity record references the DimensionAttributeSet record by its FixedDimensions field. The DimensionAttributeSet represents the combination of dimensions for the enumeration type. The DimensionAttributeSetItem records represent each dimension and enumeration value pair in the set, where the enumeration value is represented by its integer value.

The same pattern extends to the use of the NoYes BaseEnum which can be rendered in the UI as either combo boxes similar to the example above in figure 2, or as checkboxes as shown below in figure 5.

Figure 5: Alternate rendering of dimension enumerations on a form

Default dimensions

Similar to how dimension enumerations hold a set of dimensions with an associated enumeration value; a default dimension holds a set of dimensions with specific dimension values. The name default dimensions comes from the fact that these are typically entered on master data records and not directly on transactions and are used in the defaulting of values into a ledger account combination. Similar to dimension enumerations, there is no specific structure associated with these and in most instances the set is constrained by the consuming code to the dimensions available for the current ledger. A default dimension is stored in the DimensionAttributeValueSet and DimensionAttributeValueSetItem tables.

Figure 6: Default dimensions on a form

In the above example in figure 6, the user has selected a dimension value to associate with each dimension. These values are stored in the DimensionAttributeValueSet and DimensionAttributeValueSetItem tables as follows:

Figure 7: Dimension value tables query results

The MainAccountLegalEntity record holds a foreign key (FK) reference to the DimensionAttributeValueSet table which represents the combination of entered values. This table represents the set of dimensions value pairs held in the DimensionAttributeValueSetItem table.

The DimensionAttributeValueSetItem table holds one record for each entered dimension value, which references a DimensionAttributeValue. No records are stored for a dimension that has not been entered (left blank). In the DimensionAttributeValue table, there are now two records that were created when the default dimension was entered because the dimension value has now been used within the dimension framework. This links the dimension framework values with the backing entities. For performance reasons, the natural key (display value) of the dimension value is stored on the DimensionAttributeValueSetItem table.

By following the link stored in the EntityInstance field on the DimensionAttributeValue table, along with the associated ViewName on the DimensionAttribute table, we can find the record in the originating tables of CustTable (via the DimAttributeCustTable view) and DimensionFinancialTag to get to the source of the values.

In the next blog post, the storage of account structures and constraints will be explained.

Ledger account combinations - Part 3 (Structures and constraints)

Bill Frandsen — Fri, 15 Feb 2013 15:52:00 GMT

Introduction

Continuing this series of blog posts, we will cover the Structures and Constraints regions highlighted in pale yellow in the model below in figure 1.

As previously stated, the Dynamics AX 2012 dimension framework expanded on the previous release by allowing unlimited dimensions. Along with this change was the new ability for the user to specify which dimensions to include in which order when entering a ledger account combination and to constrain the values that can be entered for each segment in that ledger account combination.

Figure 1: Structures and constraints in framework

Account structures

An example of an account structure appears below in figure 2:

Figure 2: Account structure configuration form

This account structure, stored in the database in the DimensionHierarchy table, is set up to require the entry of a Main account as the first segment of a ledger account combination, followed by a customer and license plate number as subsequent segments. This is the hierarchical order definition and is stored in the database in the DimensionHierarchyLevel table.

Figure 3: Structure query results

Along with the order is the definition of constraints or the criteria that defines the valid combinations of values. In this example, all segments must have a value for the combination to be considered valid. Any existing value (already existing in the backing entity) may be entered and there are no specific restrictions on the combinations of values that are valid. This criterion is stored in the DimensionConstraintTree, DimensionConstraintNode and DimensionConstraintNodeCriteria tables.

Figure 4: Simple constraints query results

The above example in figure 4 shows the most basic constraint tree. Each of the 3 constraint nodes have a * (any existing value) constraint criteria (stored as % in SQL and shown as "<all values>" in the UI) associated with them. These constraints are used to both show what values may be entered for each segment using a lookup, and validate values entered in the segment. These constraints will eventually result in validation errors if improper values are entered for a ledger account combination.

The dimension framework allows for significantly more complex constraint trees where the value entered in on one segment drives the valid values allowed in the subsequent segment. An example of the versatility is shown below in figure 5:

Figure 5: Constraint builder form

Thus, a more complex constraint tree is shown in the following example:

Figure 6: Advanced constraint tree expanded on form

Resulting in the following constraint definition:

Figure 7: Advanced constraint tree query results

Note that in the case of entering [ 150 - B ] for a main account and customer, that the user must enter a specific license plate number as well. However, if the user enters [ 150 - W ] for a main account and customer, then no license plate number is required. In both cases however, the user will always see 3 segments in the ledger account combination, even if one of them is left blank. Examples of the effects of these structures, segments and constraints on the entry of a ledger dimension account will be provided in a subsequent blog post where we will discuss entry of ledger account combinations and their storage.

In case the user would like to only show trailing segments when they are required to be entered, then advanced rules can be combined with the account structure to provide the additional versatility. Advanced rules will be explained in the next blog post.

Ledger account combinations - Part 1 (Dimensions)

Bill Frandsen — Fri, 15 Feb 2013 15:25:00 GMT

Introduction

In Dynamics AX 2009, dimensions were limited to a minimum of three and a maximum of ten, and entered in a set order that required code customizations and database synchronization for each dimension added. In Dynamics AX 2012, the dimension framework was expanded to allow unlimited dimensions which can be dynamically created by the user, and entered in any order. The unlimited nature of the new model, coupled with taking advantage of relational database design as well as optimizing for performance requirements has led to a more complex data model than existed in the past. In this series of blog posts, we will discuss the various areas of the dimension framework, and how they work together to give a better understanding of “What happens when I create a ledger account combination?”

The model below in figure 1 shows the various areas within the dimension framework.

Figure 1: Dimensions in framework

This initial blog post covers the Dimensions, Dimension Values, Categorizations and Backing Entities regions highlighted in figure 1 above in pale yellow.

Subsequent blog posts will cover:

Dimension Enumerations and Default Dimensions
Structures and Constraints
Advanced Rules
LedgerDimensions
Advanced topics including hash keys, hashes and other key data model elements

Dimension Attributes

A dimension attribute, which will be referred to as a dimension, simply represents an additional piece of classifying information that a user would like to associate with a ledger account combination. It represents classes of things, not specific instances. Examples of things that can be used to create a dimension are Department, Cost Center, Expense Purpose, Customer, Vendor, Item – which are all classes of entities that already exist in the system; or custom entities that are specific to a particular installation such as license plate number or event name or ticket number.

When a dimension is created, the user chooses to use values for it from either an existing entity in the system such as Customers or Departments, or to create a custom list. The dimension framework keeps track of a reference for this dimension to a table in the system. For existing entities such as Customers, a reference to the CustTable table is used. For custom entities that are defined by the user, a reference to the DimensionFinancialTag table is used. This metadata about what a dimension represents is stored in the DimensionAttribute table for each dimension defined.

The following form shows an example of two dimensions, one to represent customers that already exist in the application, and another that represents a new custom list.

Figure 2: Financial dimensions form

The data is stored in the DimensionAttribute table. The SQL query below in figure 3 shows some of the basic information associated with each dimension.

Figure 3: DimensionAttribute storage query results

The Type determines whether the dimension is backed by an existing entity in the system or a custom list. It is also important to note that the dimension framework does not directly reference the existing entity backing table such as CustTable. Instead, a custom view is created to make an entity available in the system for use in the dimension framework. As of Dynamics AX 2012 R2, 36 existing entities have been enabled to be used as dimensions in the system.

It is possible for a user to create more than one dimension based on the same entity. There may be instances where an entity in the system is used for multiple different purposes when classifying transaction activity in the system. In this case, multiple dimensions can be defined for it, one for each of its purposes. A common example would be a cost center backing entity used to represent the primary cost center (e.g. selling) and the cost center the transaction is being traded against (e.g. purchasing).

Internally, special dimensions exist that are automatically created to support key functionality of the dimension framework. A primary example is the Main Account dimension. This allows a main account to be treated as a dimension by the dimension framework, but also prevents it from being used by a user to create a dimension. The other types of special dimensions are system generated ones that are used by the dimension framework for internal purposes.

Dimension Attribute Values

A dimension attribute value is a specific instance of a dimension used within the dimension framework. The values for a dimension are determined by the ViewName specified on the DimensionAttribute record. In the case of an existing entity, such as CustTable, values consist of the records in that table. In the case of a custom list, it is a specific set of records within the DimensionFinancialTag table. Values that are available for a particular dimension are viewable by clicking the “Financial dimension values” button on the Dimension details form as shown in figure 2 above. When the list is provided by an existing entity, such as CustTable, it is not editable from this form. To create a new dimension value for Customer, the user would go directly to the Customer form and create a new customer. Once created, the new customer will become available for use in the dimension framework. When the list is provided by the user as a custom list, the user will be able to modify the list directly on this form.

Example of a list of values provided by CustTable (with no values stored in the dimension framework):

Figure 4: Financial dimensions values form (existing list)

Example when provided by a custom list (with values stored in the dimension framework):

Figure 5: Financial dimensions form (custom list)

Figure 6: Dimension setup tables query results

In both of these cases, the Financial dimension values form is displaying what values exist for the entity, not what values have actually been used within the dimension framework. The dimension framework representation of these values is not created until it is used within the framework requiring it to hold a reference to it. This allows for the ability for values to be deleted that have not yet been used, and for storage size and performance optimization.

Once a dimension value is referenced requiring it to be saved by the dimension framework, it is stored in the DimensionAttributeValue table. This table is the link between the DimensionAttribute and the specific RecId of the record in the ViewName view or table referenced on the DimensionAttribute. Both the DimensionAttribute and DimensionAttributeValue records are needed to navigate back to the originating value that the user has entered.

In a system where nothing has been referenced by the dimension framework, there will be no records in the DimensionAttributeValue table.

In the next blog post, the storage of dimensions as dimension enumerations and of dimension values as default dimensions will be explained.

The Microsoft Dynamics AX 2012 extension framework – Part 3

Arthur Reginald Greef — Tue, 13 Nov 2012 18:14:30 GMT

Arthur Greef and Michael Gall.

In part 1 of this blog entry series, we explained how classes can be extended by using the Microsoft Dynamics AX 2012 extension framework and statically declared class attributes. In part 2, we described the application model elements and application model attributes that are used to extend any application object tree (AOT) object dynamically. In this blog entry, we explain to how to use model attributes and model elements to program dynamic object extensions.

Using model elements as model attributes to program dynamic object extensions

The following example shows how to create a model element object from the DocumentType base enumeration and to then use the model element to create an instance of a model attribute. The resulting model attribute is then used to cache an extension point for the InventoryPolicy1 class.

public void build()

{

SysExtModelElement element;

element = SysExtModelElementAppFactory::newFromEnum(enumNum(DocumentType), DocumentType::Doc1);

    SysExtension::addExtension(
        SysExtModelElementAppFactory::newFromClassName(classStr(InventoryPolicy1)).parmCacheKey(),
        SysExtModelAttributeInstanceFactory::newFromElement(element).parmCacheKey());

}

This extension point could be used to extend the FormLetterJournalCreate class instead of using the FormLetterJournalCreate.newSalesJournalCreate factory method currently implemented in Microsoft Dynamics AX 2012. Both methods use the DocumentType base enumerator to identify class extension points. The extension framework, however, will decouple the base FormLetterJournalCreate declaration from its extensions.

Checking extension design constraints

The SysExtensionValidatorStrategy class can be extended to check that extensions meet design constraints. For example, an extension validator can be used to check if more than one extension point maps the same model element to more than one class extension. An exception can be thrown if a design constraint requires a model element to uniquely identify a class extension.

The extension framework provides the SysExtAppClassUniqueValidator class that enforces a unique model attribute-class extension constraint for all extension classes in a class hierarchy. You can implement your own SysExtensionValidatorStrategy, and in the validate method you can implement additional validation logic (such as, allowing only extensions with particular model attributes, and so on). The validators will be executed after the dynamic builders have been executed.

Runtime extension manipulation

Model attribute extensions can be manipulated at runtime. For example, a model attribute instance that is assigned to a particular model element can be replaced with a different model attribute instance as the following example shows.

static void RuntimeExtension(Args _args)

{

SysExtModelElementApp element;

SysExtModelAttributeInstance attributeInstance;

// Get the element where you want to replace something

element = SysExtModelElementAppFactory::newFromClassName(classStr(PCAdaptor));

// Get the new attribute instance that you would like to set

attributeInstance = SysExtModelAttributeInstanceFactory::newFromValue('NewValue');

// Set for the element the new attribute instance

SysExtension::replace(element, attributeInstance);

}

The Microsoft Dynamics AX 2012 extension framework – Part 2

Arthur Reginald Greef — Tue, 13 Nov 2012 18:13:19 GMT

Arthur Greef and Michael Gall.

In this blog entry we examine the new extension framework that was shipped with Microsoft Dynamics AX 2012. In part 1 of this series, we explained how the extension framework can be used to instantiate objects from derived classes that are decorated with static class attributes. This design pattern should be used when derived class customizations are located in only one application object layer and if the customization does not change the class attribute specification that is used to annotate a derived class.

If a derived class is customized in more than one application object layer or in more than one application model, or if the class-attribute class specification is customized, then dynamic model element attributes must be used in place of static class attributes. This is because derived class customizations and class attribute customizations are merged at runtime.

This blog entry describes the model attribute design and shows how these attributes can be dynamically associated with application model elements at runtime. In the next blog entry, we’ll show how these dynamic attributes are used to dynamically extend the Microsoft Dynamics AX application.

There are two parts to this design. The first part describes how application model elements are identified by the extension framework, and the second part of the design describes how to dynamically associate dynamic attributes to these application model elements.

Model elements

The extension framework maintains a cache of model element objects that identify application object tree (AOT) model elements by name. Model elements are stored and retrieved by using a cache key that is composed of the application model element name and the classId of the SysExtModelElement base class or the classId of a class that is derived from the SysExtModelElement base class. Model elements identify run-time class specifications that can be decorated with model attributes. Model elements can either be -defined by a developer or they must reference any type of AOT object that can be identified with an AOT path. Note that all AOT model elements, not only classes, can be decorated with dynamic model elements.

Model attributes

A model element can be assigned one or more model attributes. Model elements themselves can serve as attributes as well. Model attributes have a name, and they have a property map that stores the name and the type of attribute properties. A model attribute instance is an instance of a model attribute with one or more property-value assignments. The extension framework provides a SysExtModelAttributeFactory for creating model attribute instances as shown in the following code example.

static void createAttributeInstance_Factory(Args _args)

{

SysExtModelAttributeInstance attributeInstance;

// Create an instance of a model attribute named‘String’ that

// comprises one property named ‘String’that is assigned the value ‘A’.

attributeInstance = SysExtModelAttributeInstanceFactory::newFromValue('A');

}

The following code example shows how custom attribute instances can be created. This example is for illustration only. The extension framework provides model attribute, property map, property-value map, and model attribute instance factory classes that should be used instead.

static void createAttributeInstance_Custom(Args _args)

{

SysExtModelAttribute attribute;

SysExtModelAttributeName attributeName;

SysExtModelPropertyName propertyName1, propertyName2;

SysExtModelAttributeInstance attributeInstance;

Map propertyMap;

Map propertyValueMap;

// Set the name of the attribute

attributeName = 'MyAttribute';

propertyName1 = 'MyProperty1';

propertyName2 = 'MyProperty2';

// Create property map

propertyMap = new Map(Types::String, Types::Enum);

propertyMap.insert(propertyName1, Types::String);

propertyMap.insert(propertyName2, Types::Integer);

attribute = SysExtModelAttribute::newFromParameters(attributeName, propertyMap);

// Create property map

propertyValueMap = new Map(Types::String, Types::Container);

propertyValueMap.insert(propertyName1, 'PropertyValue1');

propertyValueMap.insert(propertyName2, 2);

attributeInstance = SysExtModelAttributeInstance::newFromParameters(attribute, propertyValueMap);

}

Model element extensions

A dynamic and run-time model element extension is specified by binding a model element to one or more model attribute instances. Model element extensions are stored in the SysGlobalObjectCache.

The next blog entry (part 3) will demonstrate how the extension framework uses these model element extension objects for various dynamic and run-time extension scenarios.

The Microsoft Dynamics AX 2012 extension framework – Part 1

Arthur Reginald Greef — Tue, 13 Nov 2012 18:11:36 GMT

Arthur Greef and Michael Gall.

Microsoft Dynamics AX 2012 includes a new extension framework that can be used to reduce coupling between application foundation frameworks and their extensions.

This is the first part in a series of blogs that describes the design of the extension framework and gives examples of where this framework is used in Microsoft Dynamics AX 2012.

A typical design pattern used to extend Microsoft Dynamics AX capability is found in the bill of material (BOM) consumption calculation design. There are four parts to the extension design. The first part of the design specifies a base enumeration for each of the calculation formulas.

Base enum

      BOMFormula
            Formula0
            Formula1
            ...

The second part of the design specifies a base class and base class extensions.

AOT/Classes

       class BOMCalcConsumption{}
       class BOMCalcConsumption_Formula0 extends BOMCalcConsumption {}
       class BOMCalcConsumption_Formula1 extends BOMCalcConsumption {}
       …

The third part of the design specifies a static factory method on the base class that uses the value of a base enumeration parameter to instantiate a derived class.

class BOMCalcConsumption
{
     client server static BOMCalcConsumption construct(
            BOMFormula formula, BOMCalcData calcData)
      {
            switch (formula)

{

                case BOMFormula::Formula0:
                        return new BOMCalcConsump_Formula0(calcData);
                case BOMFormula::Formula1:
                        return new BOMCalcConsump_Formula1(calcData);
                ...
            }
           return new BOMCalcConsump_Formula0(calcData);
      }
}

In the preceding design example, the base class is tightly coupled to derived classes and needs to be modified each time that a new derived class is added to the application. In addition, a new enumeration must be added to the base enumeration. A less tightly coupled extension design that uses a class attribute and a class factory is now possible and has been used for product configuration adaptor extensions.

The extension framework uses the class attribute framework and class factory framework that is also new to Microsoft Dynamics AX 2012. These two frameworks are used to decouple base and derived classes in two steps.

1. Create a class attribute method by extending the SysAttribute class.

The following example is taken from the product configuration code in the Product information management module.

class PcAdaptorExtensionAttribute extends SysAttribute
{
PCName modelName;

public void new(PCName _modelName)

{

super();

if (_modelName == '')

{

throw error(Error::missingParameter(this));

}

modelName = _modelName;

}

public PCName parmModelName(PCName _modelName = modelName)

{

modelName = _modelName;

return modelName;

}

2. Use the preceding class attribute to add metadata to a derived class.

For example, add the following code to extend the PCAdaptor class so that a MyPCAdaptor object is created instead of a PCAdaptor object when processing a product configuration that is created from a product configuration model named “Computers”.

[PCAdaptorExtensionAttribute('Computers')]

class MyPCAdaptor extends PCAdaptor

{

protected void new()

{

super();

}

You can test that this extension works by performing the following steps.

1.       Open the Microsoft Dynamics AX development environment.
2.       Add the MyPCAdaptor class to the Application Object Tree (AOT), and then compile the class.
3.       Add a breakpoint in the PCAdaptorFactory.getAdaptorFromModelName method.
4.       Open the Microsoft Dynamics AX client.
5.       Click Product information management >Common >Product configuration models.
6.       On the action pane, in the New group, click Product configuration model.

The New product configuration model dialog opens.

7. Enter “Computers” in the Name field.
8. Enter a name in the Root component section Name field, and then click OK.

The Constraint-based product configuration model details form opens.

9.          Add an attribute to the root component in the Attributes section.
10.       On the action pane, in the Run group, click Test.
11.       Select a value for the attribute.
12.       Click OK.

The Microsoft Dynamics AX debugger should launch at the breakpoint added in step 3 in the preceding step list.

As you step though the code you will see how the SysExtensionAppClassFactory is used to create an instance of the MyPCAdaptor class.

adaptor = SysExtensionAppClassFactory::getClassFromSysAttribute(classStr(PCAdaptor), extensionAttribute);

The getClassFromSysAttribute method works by searching through the classes that are derived from the PCAdaptor class until it finds a class that has a PCAdaptorExtensionAttribute that returns a product model name that matches the name of the product configuration model being tested. In this case, the name “Computers”.

The benefits of using this new extension model are that the base and derived classes are decoupled, and it takes less code to extend the capability of the Microsoft Dynamics AX application.

Batch processing for dimension set balance rebuilds

Eric Pegors - Microsoft — Fri, 09 Nov 2012 18:56:00 GMT

When performing dimension set balance rebuilds in a batch, be sure to schedule the batches far enough apart that they do not run concurrently. Doing this will eliminate any chance for contention since a rebuild has to process the entire general journal.

Dimension set balance updates are optimized to run efficiently even if they run concurrently,

Integrating a Source Document with Budget Control

Kim Kroetsch — Tue, 17 Jul 2012 19:56:00 GMT

When adding a document extending the source document framework, the document can also be enabled for ledger budget checking. This provides the ability for the financial activity of the document to be checked to ensure funds are available to pay for those activities. Budget control is already integrated with the source document framework. This integration ensures the budget funds available check occurs at the expected times in the document's life cycle and that all of the data prerequisites for budget checking are completed.

After you have a document extending the source document framework follow these steps to enable that document to be checked for budget:

Add a new value for the integrating document to the BudgetControlSourceIntegrator enumeration
- Each value in this enumeration corresponds to a document that can be enabled for budget control from the budget control configuration form. Adding this value to the enumeration ensures that budget control data corresponding to the integrator is handled properly during budget control configuration maintenance.

Implement the SourceDocumentTypeIBudgetControl interface
- The SourceDocumentType subclass for the integrator must implement the SourceDocumentTypeIBudgetControl interface. This interface provides the following data:

Budget control source integrator value: This maps the document's implementation to its setup in budget control configuration.

Budget control category value: This determines how the amounts of the document are included in the calculation of budget funds available.

Extend the BudgetControlSourceDocumentLinePolicy class
- The BudgetControlSourceDocumentLinePolicy class provides default budget control policy for a source document line. The default policy can be extended. The extension must be decorated with the SourceDocumentExtensionAttribute based on the BusinessEvent enum and value. See the PurchOrderLineBudgetControlPolicy and VendorInvoiceLineBudgetControlPolicy classes for some examples of extending the behavior to add additional conditions for determining when budget funds available can be checked.

Extend the BudgetControlSourceDocumentLineRule class
- The BudgetControlSourceDocumentLineRule class provides default budget control processing rules for a source document line. The default rule can be extended. Similar to the policy extension, the rule extension must be decorated with the SourceDocumentExtensionAttribute based on the BusinessEvent enum and value. See the PurchOrderLineBudgetControlRule and VendorInvoiceLineBudgetControlRule classes for some examples of extending the behavior of the base rule in determining how the budget funds available check is performed against the document.

Add new data source edit methods on BudgetControlConfiguration data source on the BudgetControlConfiguration form to allow for budget checking to be enabled and disabled at the document level
- Add a method calling the setSourceIntegratorEnabled() method. This method will provide the option to enable and disable budget checking for the source document. Then to refresh the form display when the value changes, call the setEnabledSourceDocuments() method.

Example: editVendorInvoiceEnabled()

public edit NoYes editVendorInvoiceEnabled(boolean _set, NoYes _isEnabled)

{

BudgetControlSourceIntegrator sourceIntegrator = BudgetControlSourceIntegrator::VendorInvoice;

boolean isSet;

if (_set)

{

// Set whether vendor invoice budget control is enabled.

isSet = this.setSourceIntegratorEnabled(sourceIntegrator, _isEnabled);

if (isSet)

{

element.setEnabledSourceDocuments();

}

return enabledSourceIntegrators.in(sourceIntegrator);

}

Add a method calling the setSourceIntegratorDoBudgetCheckOnEntry() method. This method will provide the option to specify whether the source document will perform a budget check at line item entry.

Example: editVendorInvoiceDoCheckOnEntry()

public edit NoYes editVendorInvoiceDoCheckOnEntry(boolean _set, NoYes _doBudgetCheckOnEntry)

{

BudgetControlSourceIntegrator sourceIntegrator = BudgetControlSourceIntegrator::VendorInvoice;

if (_set)

{

// Set whether vendor invoice do budget check on entry.

this.setSourceIntegratorDoBudgetCheckOnEntry(sourceIntegrator, _doBudgetCheckOnEntry);

}

return doBudgetCheckOnEntrySourceIntegrators.in(sourceIntegrator);

}

Add controls to the form on the SourceDocuments tab page to expose the edit methods that were added.
Add code to maintain the form controls in the setEnabledSourceDocuments() and setVisibleSourceDocuments() methods.

These additional extension areas can be considered depending on the requirements of the new source document:

Add extension attributes to enable budget checks when the accounting distribution form is interacted with from the source document. This allows the budget funds available check to also occur after interacting with the accounting distributions form.
- Add the SourceDocumentExtensionAttribute based on the SourceDocument enum and value to the BudgetControlAccDistFormViewExtension and BudgetControlAccDistViewModelExtension classes.

Add calls for on-demand checks
- Budget checking is performed for a source document enabled for budget control through budget control configuration when the document is transitioned to a Completed state. In addition to this state transition, budget checking is performed based on the option in the budget control configuration to do the budget check on line entry. Additional calls can be added to perform a budget check at other times by calling one of the submitOnDemand() methods on the SourceDocumentProcessorFacade class. Using this method will ignore the setting of the configuration option to perform the check on line entry. Examples of when this can be used are workflow actions that should perform a budget check or a user-initiated action such as the "Perform budget check" action on the action pane.

Step 6: Implement confirmation/posting of your document

Jarek Wyganowski — Fri, 11 May 2012 02:17:00 GMT

Posting of your document usually consist of creating accounting entries in ledger and updating your document to posted state. Source Document Framework will help you create accounting.

a) Add code necessary to perform state update of your document during posting (for instance, you can add a field IsPosted to your document header and set it to Yes when the document is posted successfully) . This functionality will usually reside on a posting class specific to your document.

b) Wire your posting class to a “Post” button on your form through a menu item.

c) Make sure the source document implements parmCurrentVoucher() - this is used when generating accounting during document confirmation/posting.

d) Inside your confirmation/posting code, submit your document to the Source Document Framework calling:

SourceDocumentProcessorFacade::submitSourceDocumentImplementation(myDocumentHeader, true, SourceDocumentAccountingStatus::Completed);

The code above will generate accounting.

e) To validate the accounting, on your document form action pane you can add a “Voucher” button to view the voucher for your posted document.

The button should use LedgerTransVoucher display menu item.
The LedgerTransVoucher form needs to be modified to limit the vouchers to only those that are related to your document. Follow the pattern used for PurchTable: see form method named updateQueryForPurchTable() for an example of how to apply ranges on that form – your code should be very similar to code in that method. Name your new method updateQueryForMyDocument().

Apply your range during initialization of the form calling updateQueryForMyDocument() from the form init() method - you will find examples of that examining existing code in the LedgerTransVoucher form init() method.

Step 5: Add code to distribute and journalize source document amounts

Jarek Wyganowski — Mon, 07 May 2012 23:36:00 GMT

There might be a need to create new monetary amounts but that is optional and you may find existing monetary amounts sufficient. It depends if existing monetary amounts are a good fit for your document and have appropriate names to display on accounting distributions form. Either new or existing MonetaryAmount enum values will be used in your code creating distributions.

a) Create a class extending AccountingPolicy. Using framework naming standards name this class AccPolicyMyBusinessEvent .
Decorate it with SourceDocumentExtensionAttribute:

[SourceDocumentExtensionAttribute(enumNum(BusinessEvent_MyDocument), BusinessEvent_MyDocument::MyBusinessEvent)]

b) (Optional) Add an additional value (MyValue) to MonetaryAmount enum. This will be used later to identify your specific amount when you add code to calculate all amounts that need to be distributed for your document in calculateSourceDocumentAmountMap method on your source document line classes.

c) (Optional) In case you added your value to MonetaryAmount enum – update SourceDocumentMonetaryAmountModel class. Methods initMonetaryAmountChildMap() and optionally initMonetaryAmountParentMap() will need to be updated.

d) (Optional) In case you added your value to MonetaryAmount enum – you may need to update SourceDocumentAmountFormTreeBuildHelper.initMonetaryAmountTreePostionMap() if you have specific requirements about sequencing of monetary amounts in the accounting distribution form.

e) Create a class extending AccountingDistributionRule. Using framework naming standards name this class AccDistRuleMyDesiredAction where “MyDesiredAction” describes the business event associated with the rule (e.g. AccDistRuleSaleOfProductTax). Decorate it with SourceDocumentExtensionAttribute:

[SourceDocumentExtensionAttribute(enumNum(BusinessEvent_MyDocument), BusinessEvent_ MyDocument::MyBusinessEvent, MonetaryAmount::MyValue)]

MyValue could be either an existing value or a newly created value (see optional steps 5 b-d).
Implement abstract methods parmSide() and parmLedgerPostingType().

f) Revisit your classes extending SourceDocumentLine which have monetary amounts to distribute. On each of them override method calculateSourceDocumentAmountMap() to return map of all source document amounts which need to be distributed.

g) (Optional) Create your own account dimension list provider. To do that, you need to first add a value to MainAccountDimensionListProviderType enum identifying the provider (let’s call it MyType). Next create a class that extends MainAccountDimensionListProvider. Decorate the class with SourceDocumentExtensionAttribute:

[SourceDocumentExtensionAttribute(enumNum(MainAccountDimensionListProviderType), MainAccountDimensionListProviderType::MyType)]

h) (Optional) Create an interface to abstract out usage of your provider and get required data for SourceDocumentLineItem classes that will implement this interface. Name it after the new enum value: SourceDocumentIMyType.

i) (Optional) Revisit your source document class (MyDocumentSourceDocument) and implement the SourceDocumentIMyType interface on it.

j) (Optional) Create provider class inheriting from MainAccountDimensionListProvider. Using framework naming standards name it MyTypeMainAccountDimensionListProvider. Decorate it with SourceDocumentExtensionAttribute:

[SourceDocumentExtensionAttribute(enumNum(MainAccountDimensionListProviderType), MainAccountDimensionListProviderType::MyType)]

Implement populateMainAccountDimensionList() method to return the list containing the appropriate main account.

k) (Optional) Modify AccountingRule class adding method canUseMyTypeMainAccountDimensionListProvider() which determines under which conditions your provider should be used. It will usually be determined by source document extension class implementing correct interface, but could be other condition as well:

public boolean canUseMyTypeMainAccDimListProvider()
{
Object sourceDocument = sourceDocumentLineItem.parmSourceDocument();
return (sourceDocument is SourceDocumentIMyType);
}

l) (Optional) Modify MainAccountDerivationDistributionRule and/or MainAccountDerivationJournalizingRule to initialize the account list based on new provider. Code will be added in populateMainAccountList() method.

The distributions part should be working now and you should be able to see distributions on your document’s form clicking on distributions buttons which you added earlier.

Now you need to add necessary code for proper journalization of your document.

Usually you will just want to put the balancing amount into certain account (like Vendor Balance). If you need just that, do the following:

m) Create a class extending AccountingJournalizingRule. Using framework naming standards name this class AccJourRuleMyDesiredAction where “MyDesiredAction” describes the action you are performing which affects your distributions (e.g. AccJourRuleSaleRevenue). Decorate it with SourceDocumentExtensionAttribute:

[SourceDocumentExtensionAttribute(enumNum(BusinessEvent_MyDocument), BusinessEvent_ MyDocument::MyBusinessEvent, MonetaryAmount::MyValue)]

MyValue could be either newly created value or an existing one.
Implement abstract methods parmSide() and parmLedgerPostingType().

n) Go back to your source document class and inherit the right source document interface on it (for example SourceDocumentIParty for vendor balance) - it will tell the MainAccountDerivationJournalizingRule class (through canUse<ProviderType> method) to use the specific DimensionListProvider during journalization (see code inside MainAccountDerivationJournalizingRule.populateMainAccountList() for more info).

Rarely, your document will have more demanding journalization requirements than just putting a balance amount into a balance account. If that is the case you may need to implement journalization rules with steps analogous to implementing distribution generation described above.

After this step the button which you added earlier on your document’s form which invokes menu item SubledgerJournalAccountEntries should display all subledger account entries for your document allowing you to test distribution and journalization rules.

Next - Step 6: Implement confirmation/posting of your document

Step 4: Add Source Document Framework forms to your document UI

Jarek Wyganowski — Thu, 03 May 2012 17:11:00 GMT

This initial wiring will just display empty windows as you didn’t create code which would calculate distributions. But it is good to do it now to be able to have a quick visual test when you later add code related to distributions.

a) Make sure you supplied both Label and SingularLabel for your document header and line tables (see table properties) as those are used by the distributions form.

b) On your document form action pane add a button to view distributions for your document. The display menu item which opens the AccountingDistributions form for this purpose is AccountingDistributionsDocumentView.

c) On your document form action pane add a button to edit distributions for your document. The display menu item which opens the AccountingDistributions form for this purpose is AccountingDistributions.

d) On your document form action pane add a button to view subledger journal entries for your document. The display menu item for that purpose is SubledgerJournalAccountEntries.

e) On your document form line action pane add a button to edit distributions for your source document line. The display menu item which opens the AccountingDistributions form for this purpose is AccountingDistributions.

f) For all menu items you need to setup security properly for roles that need access to your document. Along with that you may decide to create your own menu items instead of reusing existing menu items, pointing the new menu items to the same forms as mentioned above and customizing both menu items and security based on those menu items to your needs.

Below is an example of UI wiring to Source Document Framework taken from Vendor Invoice entry form (VendEditInvoice):

Next - Step 5: Add code to distribute and journalize source document amounts

Step 3: Perform initial wiring to Source Document Framework – document classes

Jarek Wyganowski — Tue, 01 May 2012 13:42:00 GMT

Now you need to implement few classes representing your source document.

a) Create a class which extends SourceDocumentType.

Using framework naming standards name this class MyDocumentSourceDocumentType.
Implement all abstract methods (see examples in the following existing classes: CustInvoiceSourceDocType, VendorInvoiceSourceDocType, PurchaseOrderSourceDocumentType)

- parmModule(): used to determine whether it is valid to add entries to subledger for given module.

- parmSourceDocumentHeaderRootNodeLabel(), parmSourceDocumentLineRootNodeLabel() : used by UI to display proper label for document header or lines respectively.

- parmSubledgerJournalEntryType(): amounts (including matching amounts) are balanced by the framework across subledger journal entry types.

- parmSubledgerJournalRelievingMethod(): in case of matching it specifies relieving method for amounts of the upstream document.

Decorate the class with SourceDocumentExtensionAttribute(s) with appropriate parameters from the newly created enums.

[SourceDocumentExtensionAttribute(enumNum(SourceDocument_MyDocument), SourceDocument_MyDocument::MyDocument)]

b) Create a class which extends SourceDocument.

Using framework naming standards name this class MyDocumentSourceDocument.
Implement initializeImplementation() which is intended to set up internal state (for examples see VendorInvoiceSourceDoc.initializeImplementation(), PurchaseOrderSourceDocument.initializeImplementation())
Decorate this class with SourceDocumentExtensionAttribute(s) with appropriate parameters from the newly created enums.

[SourceDocumentExtensionAttribute(enumNum(SourceDocument_MyDocument), SourceDocument_MyDocument::MyDocument, tableNum(MyDocumentHeader))]

Create an enum for your business event.

- Using framework naming standards name it BusinessEvent_MyDocument.

- Values would list all business event types specific to your document. Add values: None = 0, MyBusinessEvent = 1.

- This will be used by attributes on extensions of AccountingDistributionRule, AccountingJournalizingRule and AccountingPolicy which you will create later.

Implement appropriate SourceDocument interfaces – as a minimum SourceDocumentIDataProvider interface providing the following methods:

- parmDistributionTemplateRecId(): should return a RecId reference of a template. If not empty, the template will be used to populate ledger dimension allocation list

- documentsBusinessEvent(): should return the BusinessEvent based on your newly created BusinessEvent_MyDocument enum

- parmAccountingDate(): should return the accounting date for the document

- parmBusinessEventDate(): the simplest implementation is already provided on the SourceDocument class

- parmDefaultDimension(): if default dimension is provided, it is used by the framework to build ledger dimension

c) Create class(es) extending SourceDocumentLineItem.

If your document has amounts to distribute on both header and lines you may need to create two such classes.
Using framework naming standards name those classes MyDocumentLineSourceDocumentLineItem, MyDocumentSourceDocumentLineItem respectively.
Implement the following abstract methods (for examples see the existing implementations: CustInvoiceSourceDocLineItem, CustInvoiceLineSourceDocLineItem, VendorInvoiceSourceDocLineItem, VendorInvoiceLineSourceDocLineItem, PurchOrderSourceDocumentLineItem, PurchOrderLineSourceDocumentLineItem)

- calculateLegalEntityRecId(): should return reference to CompanyInfo table record representing legal entity of the document line

- calculateSourceDocumentAmountMap(): should return object of type SourceDocumentAmountMap representing collection of amounts to distribute for the line

- documentsBusinessEvent(): should return a business event documented by given source document line. In the simplest form the code will look like the following:

return new BusinessEvent(enumNum(BusinessEvent_MyDocument), BusinessEvent_MyDocument::MyBusinessEvent);

- initializeImplementation() - intended to set up internal state

- parmTransactionCurrencyCode() – should return the currency for the line

Decorate each class with SourceDocumentExtensionAttribute(s) with appropriate parameters from the newly created enums.

Attribute for line class:
[SourceDocumentExtensionAttribute(enumNum(SourceDocumentLine_MyDocument), SourceDocumentLine_MyDocument::MyDocumentLine)]

Attribute for totals line class:
[SourceDocumentExtensionAttribute(enumNum(SourceDocument_MyDocument), SourceDocumentLine_MyDocument::MyDocumentTotalsLine)]

d) Keep document state persisted by the source document framework in sync with your document state. This is done by overwriting table insert() and update() methods on your document tables.

Document header – insert()

SourceDocumentProcessorFacade::submitSourceDocumentImplementation(this);

SourceDocumentProcessorFacade::submitSourceDocumentLineImplementation(this);

super();

Document header – update()

super();

SourceDocumentProcessorFacade::submitSourceDocumentLinesForHeader(this, SourceDocumentLineAccountingStatus::FullyDistributed);

Document line – insert()

SourceDocumentProcessorFacade::submitSourceDocumentLineImplementation(this);

super();

Document line – update()

super();

SourceDocumentProcessorFacade::submitSourceDocumentLineImplementation(this);

Next - Step 4: Add Source Document Framework forms to your document UI

Step 2: Perform initial wiring to Source Document Framework – tables and maps

Jarek Wyganowski — Thu, 26 Apr 2012 22:14:00 GMT

The Source Document Framework (Accounting Framework) will provide functionality necessary to record business events and create accounting for the newly created document – accounting distributions and subledger journal entries. But you will need to inform the framework how to deal with your document.

a) Reference source document header

Modify the table definition of your document header table adding SourceDocumentHeader field of type SourceDocumentHeaderRecId.
Add your header table to SourceDocumentHeaderImplementation map (under AOT/Data Dictionary/Maps/SourceDocumentHeaderImplementation/Mappings) – adding a mapping to SourceDocumentHeader field from your header table.
Create an enum following the naming convention SourceDocument_MyDocument. Add values None = 0, MyDocument = 1. This enum and its values will be used by SourceDocumentExtensionAttribute to bind your classes to the framework in later steps.
Treat map as an interface: implement all methods from the map on the table – namely:

- parmSourceDocHeaderTypeEnumValue(): return appropriate value from the SourceDocument_MyDocument enum you created earlier

- parmSourceDocHeaderTypeEnumName(): return the name of the SourceDocument_MyDocument enum you created earlier

See existing implementations on CustInvoiceTable, VendInvoiceInfoTable and PurchTable tables for examples related to Customer Invoice, Vendor Invoice and Purchase Order documents respectively.

b) Reference source document line

Modify the table definition of your document line table adding SourceDocumentLine field of type SourceDocumentLineRecId.
Add your line table to SourceDocumentLineImplementation map (under AOT/Data Dictionary/Maps/SourceDocumentLineImplementation/Mappings) – adding a mapping to SourceDocumentLine field from your line table.
Create an enum following the naming convention SourceDocumentLine_MyDocument. Add values None = 0, MyDocumentLine = 1. This enum and its values will be used by SourceDocumentExtensionAttribute to tie your classes to the framework in later steps.
Treat map as an interface: implement all methods from the map on the table – is this step you will use new base enums created in prior step. The following methods need to be implemented:

- parmSourceDocLineTypeEnumValue(): return appropriate value from the SourceDocumentLine_MyDocument enum you created earlier

- parmSourceDocLineTypeEnumName(): return the name of the SourceDocumentLine_MyDocument enum you created earlier

- parmSourceDocumentHeader(): should return corresponding SourceDocumentHeader record

- parmParentSourceDocumentLine(): should return source document line which is a parent for given source document line (for example – tax line could return its parent invoice line)

- parmExchangeRateDate(): should return date of the exchange rate for given line

See existing implementations on CustInvoiceLine, VendInvoiceInfoLine and PurchLine tables for examples related to Customer Invoice, Vendor Invoice and Purchase Order documents respectively.

c) You may need to also modify your header table to be able to act like a line if you expect any accounting related to monetary amounts on the header. In AX 2012 an example of header related amount for which distributions are being created is Round-off (VendInvoiceInfoTable.InvoiceRoundOff).

In this case the header table needs do go through the same steps as the above step 2b described for the line table.
Add the enum value for the totals line (MyDocumentTotalsLine = 2) to the SourceDocumentLine_MyDocument enum which you created in step 2b.

Below is a data model diagram outlining the important relationships between your tables and the framework tables:

Next - Step 3: Perform initial wiring to Source Document Framework – document classes

Step 1: Prerequisite - create your document

Jarek Wyganowski — Thu, 26 Apr 2012 22:11:00 GMT

At this point you should not be concerned about Source Document Framework, but only about the document storage, UI and perhaps some domain logic responsible for processing the document. Storage usually consists of two tables, one for storing document header information (MyDocumentHeader) and another one to store document lines information (MyDocumentLine). The UI usually requires creating a list page and a document entry form. The List page and the form would be using the domain logic tables and classes that implement whatever functionality is required for the document.

The subsequent steps will be outlining how to employ Source Document Framework for your newly created document.

For additional examples and detailed code samples refer to existing source document extensions in Dynamics AX 2012.

A good example of a less complex document is Free Text Invoice. Good examples of complex documents are Vendor Invoice and Purchase Order.

Refer to classes and tables related to SourceDocument_CustomerInvoice and SourceDocumentLine_CustomerInvoice enums for Free Text Invoice source document extension code.

Refer to classes and tables related to SourceDocument_VendorInvoice and SourceDocumentLine_VendorInvoice enums for Vendor Invoice source document extension code.

Refer to classes and tables related to SourceDocument_ProductOrder and SourceDocumentLine_ProductOrder enums for Purchase Order source document extension code.

Next - Step 2: Perform initial wiring to Source Document Framework – tables and maps

Extending the Source Document Framework

Jarek Wyganowski — Thu, 26 Apr 2012 21:59:00 GMT

The upcoming series of blog posts is created to help developers new to Source Document Framework flatten the learning curve and quickly get up and running with their own source document extensions.

The information presented here is covering the mainstream scenario.

It is divided into 6 steps:

Step 1: Prerequisite - create your document

Step 2: Perform initial wiring to Source Document Framework – tables and maps

Step 3: Perform initial wiring to Source Document Framework – document classes

Step 4: Add Source Document Framework forms to your document UI

Step 5: Add code to distribute and journalize source document amounts

Step 6: Implement confirmation/posting of your document

Welcome!

John Healy - Microsoft Dynamics — Wed, 25 Apr 2012 18:30:47 GMT

Hello!

Welcome to the Microsoft Dynamics AX Global Financial Management (GFM) team blog. My name is John Healy. I am a Principal Software Architect on the GFM team. I’m very excited to launch this blog. This blog will focus on providing technical and application information related to the frameworks and applications for which the GFM team is responsible. Our first series of blog postings will be focusing on extending the source document framework. The source document framework was introduced in AX 2012. It provides a model for defining source documents, documenting business events, and recording the accounting impact of the business events.

Stay tuned!
John