Microsoft Dynamics AX development

Archive for March, 2014

Create or extend Data Migration Framework

Create the Staging Table

1) In the AOT create a staging table for the entity, with the following table properties:

Property Value
SaveDataPerCompany NO
SupportInheritance NO
TableType Regular
ConfigurationKey DMF
ValidTimeStateFieldType None

2) Create fields with the following properties

Field name EDT Enum
DefinitionGroup DMFDefinitionGroupName
IsSelected DMFIsSelected NoYes
TransferStatus DMFTransferStatus
ExecutionId DMFExecutionId


3) Create field groups with the following properties:

Field group name Label Field
ExecutionList Execution list DefinitionGroup, IsSelected, TransferStatus, ExecutionId
Enabled Enabled OPTIONAL. Fields from the staging table which you want to make part of   template by default
<<FunctionName_Sequence>>Ex.: GeneratePostalAddress_2 <<Description offunction>> Fields from staging table which are the source for the   specified method (fields that are used in the method)
NB.: The field group “Generate” must be created even if there are no fields in them. If in the class is present the method “Generate”, the DMF table must have the associated field group (empty or not). For example, the table “DMFProductEntity” has a field group named GenerateItemGroupCompany_2”,  that is empty, but the class “DMFProductEntityClass” has a method called “GenerateItemGroupCompany”.

4)      Create a primary index for the table:

Index name Properties Field(s)
<<any name>>Ex.: Idx
AllowDuplicates NO
AlternateKey YES
DefinitionGroup, ExecutionId, fields from staging table   to define uniqueness

5)      Specify the relationship between the staging table and the target table

Create an Enum fields in the target entity

The Enum field in the target entity is represented by a string field in the staging table. You must create a new extended data type (EDT) of type string, and of appropriate length to take the enum label strings.


HcmEmployment.EmploymentType = Enum HcmEmploymentType
DMFEmployeeEntity. EmploymentType = Type String -> EDT = DMFEmploymentType



If the target table contains fields that are RecIds from other tables, you must convert the natural key to a RecId. There are two options:

  • Add a data source so that the referenced table can be added to the target entity query

  • Create a function

Add a datasource

For example, the target VendTable contains VendExceptionGroup, which is a RecId that comes from VendExceptionGroup Table.


In this case, the staging table must include
VendExceptionGroup. We add the table in the query, under VendTable datasource. The relationship must be specified manually.


The staging field DMFVendorEntity.VendExecptionGroup must be mapped to the target field query for DMFVendorTargetEntity . DS:VendExceptionGroup.VendExceptionGroup

Create a function

Create a method on the entity class to convert the string to a RecId. For example, the method DMFCustomerEntity.GenerateCompanyIdNAF:

public container GenerateCompanyIdNAF(boolean _stagingToTarget = true)
    CompanyNAFCode  companyNAFCode;
    container       res;

    if (_stagingToTarget)
        select firstOnly1 RecId from companyNAFCode where companyNAFCode.CompanyIdNAF == entity.CompanyIdNAF;
        res = [companyNAFCode.RecId];
        if (target.CompanyNAFCode)
            select firstOnly1 CompanyIdNAF, RecId from companyNAFCode where companyNAFCode.RecId == target.CompanyNAFCode;

        res = [companyNAFCode.CompanyIdNAF];

    return res;

When you create a function approach, you must create a field group for the staging table, and the return fields on the target must be specified in the getReturnFields method in the entity class.

case methodStr(DMFCustomerEntityClass, GenerateCompanyIdNAF) :
     con += [fieldstrToTargetXML(fieldStr(CustTable, CompanyNAFCode))]; 

Create a class

1)      In the AOT create a class for the entity with the following properties:

  • [DMFAttribute(true)]

  • DMFClassName extends DMFEntityBase

  • Declare the object for the staging table with the name “entity”.

  • Declare the object for the main table for the target entity with the name “target”.

  • The following example shows how the DMFBEMATableEntityClass is declared.

public class DMFBEMATableEntityClass extends DMFEntityBase
    DMFBEMATableEntity entity;
    BEMATable target;

2)      Create the new method:

  • Must take the staging table as parameters

  • The value entity should be initialized from a parameter. The following example shows the DMFBEMATableEntity new method

public void new(DMFBEMATableEntity _entity)
    entity = _entity;

3)      Create the construct method:

  • Must take the staging table as a parameter

  • Must create and return the object of the current class by using a parameter. The following example shows the DMFBEMATableEntity construct method

public static DMFBEMATableEntityClass construct(DMFBEMATableEntity _entity)
    DMFBEMATableEntityClass entityClass = new DMFBEMATableEntityClass(_entity);
    return entityClass;

4)      Create the setTargetBuffer method:

  • A target entity can have multiple data sources. One of the data sources is the main table that represents the entity. In the setTargetBuffer method, the parameter _dataSourceName represents the data sources that are present in the target entity query

  • Depending on the data source, you may need to initialize a local instance of the table for the data source. The local instance can then be used in the functions that are required for data migration. The target should be initialized by the main table that represents the target entity

public void setTargetBuffer(Common _common, Name _dataSourceName = "")
        case tableNum(BEMATable) :   
            target = _common;

5)      Set the RunOn property of the class to the value CalledFrom

Write functions to import and export data

You can map data from the staging to the target table in two ways:

  1. Assign fields: A field from staging is directly assigned to a field in target. In this case the data types for the staging and target fields must be same

  2. Write a function to transform the field values from staging to target. You can write X++ functions to transform and map data from staging to target

Write functions

Data import and export functions that you define must perform the following actions:

  1. Input (Source): the entire staging record is available as a local variable to the class, so there is no need to pass any parameters to this class

  2. Output (Target):  as a result of executing the function, zero or multiple fields in the target entity are set. The return type of the function is a container, which can hold zero or more values to set on the target

The sequence of values that are returned by a particular function must be defined in the getReturnFields method.

addStagingLink method

The addStagingLink method is used to define the relationship between the staging and target table when it cannot be defined by using the relations property of the staging table.

The target query and the staging record are available in the method, so the range between target and staging can be added using code.

Example: DMFEmployeeEntityClass

public static Query addStagingLink(Query query, TableId _entityTableId, Common _staging)
    QueryBuildDataSource    qbd;

    qbd = query.dataSourceTable(tableNum(HcmWorker));
    return query;

getReturnFields method

The getReturnFields method is used to specify the default output or target fields for the functions that are used for data migration.

Parameters include:

  •  _entity: entity name

  • _name: function name

The function must return a container, as well as the name of the data source in the target entity query with which the method should be executed, and the name of the data source field in the target entity query which should be initialized by executing the function.

public static container getReturnFields(Name _entity, MethodName _name)
    DataSourceName dataSourceName = queryDataSourceStr(DMFEmployeeTargetEntity, HcmEmploymentDetail);
    Container      con            = [dataSourceName];

    Name fieldstrToTargetXML(FieldName _fieldName)
        return DMFTargetXML::findEntityTargetField(_entity,dataSourceName,_fieldName).XMLField;

    switch (_name)

        case methodStr(DMFEmployeeEntityClass,GenerateReasonCode) :
            con += [fieldstrToTargetXML(fieldStr(HcmEmploymentDetail, TransitionReasonCode))];

        //change datasource
        case methodStr(DMFEmployeeEntityClass,GenerateDefaultDimension) :
            dataSourceName = queryDataSourceStr(DMFEmployeeTargetEntity, HcmEmployment);
            con            = [dataSourceName];
            con += [fieldstrToTargetXML(fieldStr(HcmEmployment, DefaultDimension))];
        default :
            con = conNull();

    return con;

This tells the migration tool which table and field, the value passed back from the generate method should go.



Tag Cloud