Microsoft Dynamics AX 2012 DMF – Composite Entity Primer
Purpose: The purpose of this document is to illustrate how to use Dynamics AX 2012 DMF for import of custom data. In this particular primer I’ll be focusing on Entity type = Composite Entity.
Challenge: Data model changes in Dynamics AX related to high normalization and introduction of surrogate keys made import of data more complex. Data Migration Framework for Microsoft Dynamics AX 2012 was designed and developed to address this challenge. Data Migration Framework for Microsoft Dynamics AX 2012 provides architectural foundation for data import process as well as it ships with the numerous standard templates covering most important types of business data.
Solution: Dynamics AX 2012 ships with the number of DMF templates which can be used in data import scenarios. For import of custom data Data Migration Framework “Create custom entity for migration” wizard which assists you in creating of required DMF objects infrastructure. A composite entity groups multiple related entities together. In my example composite entity will combine header (AlexTable) and lines (AlexLine) entities together.
Data Model:
Table Name | Table Description |
AlexParent | Sample table |
AlexTable | Sample header table which extends from sample table |
AlexLine | Sample lines table |
Data Model Diagram:
Sample Data Model
<![if !vml]>![]()
<![endif]>
<![endif]>Process Overview:
<![if !vml]>![]()
<![endif]>
<![endif]>Walkthrough:
Project1
Please note that I initially created 3 tables to implement a data model for this scenario
AlexParent
AlexTable
AlexLine
Processing group: Alex
Custom entity wizard: AlexTable
Welcome
Select a table
Dynamics AX Error: Table with inheritance is not supported by wizard
Please note that Custom entity wizard doesn’t support Table inheritance, that’s why I had to make a data model change to remove Table inheritance from AlexTable table
AlexTable: Correction to the data model to remove Table inheritance
Select code generation parameters
Wizard complete
After Custom entity wizard is completed DMFAlexTableEntity project will be created automatically
Project: DMFAlexTableEntity
Please note that DMFAlexTableEntityClass class, DMFAlexTableEntity table and DMFAlexTableTargetEntity query have been generated by Create entity wizard automatically
Class: DMFAlexTableEntityClass
Table: DMFAlexTableEntity
Query: DMFAlexTableTargetEntity
Custom entity wizard: AlexLine
Welcome
Select a table
Select a code generation parameter
Wizard complete
After Custom entity wizard is completed DMFAlexLineEntity project will be created automatically
Project: DMFAlexLineEntity
Please note that DMFAlexLineEntityClass class, DMFAlexLineEntity table and DMFAlexLineTargetEntity query have been generated by Custom entity wizard automatically
Class: DMFAlexLineEntityClass
Table: DMFAlexLineEntity
Query: DMFAlexLineTargetEntity
Target entities: Alex
Child entities: Alex
Tables: AlexTable and AlexLine
Remark: Added Replacement key (ID) to DMFAlexLineEntity staging table in order to do ID -> RecId (AlexTable) translation via function
Class: DMFAlexLineEntityClass
Remark: Added GenerateAlexTableLink method to provide a function
Table: DMFAlexLineEntity
Remark: Added GenerateAlexTableLink_1 field group to provide a function
Class: DMFAlexLineEntityClass - Source code
publicstaticcontainer getReturnFields(Name _entity, MethodName _name) { DataSourceName dataSourceName = queryDataSourceStr(DMFAlexLineTargetEntity, AlexLine); Container con = [dataSourceName]; Name fieldstrToTargetXML(FieldName _fieldName) { return DMFTargetXML::findEntityTargetField(_entity ,dataSourceName, _fieldName).XMLField; } switch (_name) { casemethodStr(DMFAlexLineEntityClass, GenerateAlexTableLink) : con += [fieldstrToTargetXML(fieldStr(AlexLine, AlexTable))]; break; default : con = conNull(); } return con; } |
publicContainer GenerateAlexTableLink(boolean _stagingToTarget = true) { container res; AlexTable AlexTable; if (_stagingToTarget) { select AlexTable where AlexTable.ID == entity.ID; if(!AlexTable) { AlexTable.ID = entity.ID; AlexTable.insert(); } res = [AlexTable.RecId]; } else { res = [target.AlexTable]; } return res; } |
CSV File: Alex
This is how the source file looks like for Alex
Screenshot | Text |
 | <AlexTable>ID,FieldC,FieldD <AlexLine>ID,FieldE,FieldF 1,C1,D1 1,E1,F1 |
Please note that the first 2 rows are header rows for AlexTable and AlexLine respectively, after that we have business data in CSV format
Select entities for processing: Alex
Generate source mapping: Alex
Please note that there's no need to create mapping manually, this mapping is already pre-created for you.
Select entities for processing group: AlexTable
Once file is specified you can preview the data by pressing "View source data" button, then the data will be displayed in Preview pane.
Map source to staging – Mapping details: AlexTable
Map source to staging – Mapping visualization: AlexTable
Map staging to target – Mapping details: AlexTable
Map staging to target – Mapping visualization: AlexTable
Select entities for processing group: AlexLine
Map source to staging – Mapping details: AlexLine
Map source to staging – Mapping visualization: AlexLine
Map staging to target – Mapping details: AlexLine
Map staging to target – Mapping visualization: AlexLine
Dynamics AX Error: Argument to method getFieldValue out of range
Solution: Argument to method getFieldValue out of range
Remark: Provided TitleField1 and TitleField2 for AlexTable and AlexLine tables in order to resolve Argument to method getFieldValue out of range issue
Execute source to staging: After you execute source to staging data import the system will confirm how many records were synchronized with staging table
Execution history: The results and time consumed can be seen in Execution history form
Execute staging to target: After you execute staging to target data import the system will confirm how many records were synchronized with AX business data tables. This is when the data gets populated in AX
Execution history: The results and time consumed can be seen in Execution history form
Result:
Dynamics AX – Table Browser
AlexTable
AlexLine
Versions: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Data Migration Framework v2.0
Summary: In this document I explained how to use Data Migration Framework in Microsoft Dynamics AX 2012 in order to import custom data (header and lines). This approach is especially recommended for large scale data migrations and allows for much better performance comparing to usage of Microsoft Dynamics AX 2012 Excel Add-in. Data Migration Framework in Microsoft Dynamics AX 2012 already ships with numerous standard templates for most important types of business data. Please note that v2.0 release has support for 26 business entities. Data migration is iterative process and the fact that DMF provides flexible validation capabilities facilitates this process significantly.
Author: Alex Anikiiev, PhD, MCP
Tags: Dynamics ERP, Dynamics AX 2012, DMF, Data Migration Framework, Data Import, Data Conversion, Data Migration, Composite Entity, Table Inheritance
Note: This document is intended for information purposes only, presented as it is with no warranties from the author. This document may be updated with more content to better outline the concepts and describe the examples.