Data Migration Framework – Create a Custom Entity For Migration

Our team are using the Data Migration Framework to import data into Dynamics AX 2012.  We have created a lot of custom entities, which has been challenging given the lack of documentation on the subject.  I thought I’d share a tutorial which I have written on creating a custom entity.


1. Go to Data Migration Framework –> Common –> Create a custom entity for migration.

2. Select the table you wish to create as an entity and click finish.



3. Click on Yes to define the relationships.


N.B. This seems to error occasionally.  If it does, you must manually create any elements the wizard has not created for you.  The structure of your project should look like the screen shot below.  Your project may contain EDTs which is fine.  You project is created as a private project.



The Staging Table

4. The table which is created is the table you will load the staging data into.  I have removed the fields I do not require for the data import, but this is not a necessary step.

5. The wizard creates four standard fields which are used in the DMF.  Definition group, ExecutionId, TransferStatus and IsSelected.

  • Change the EDT on the isSelected Field to DMFIsSelected.
  • Change the enumType of the TransferStatus field to DMFTransferStatus.

6. Remove the relation DMFExecution1.

7. Create a relation between the staging table and the table you are populating.



Custom Method/Function

In this example, I want the Description field to be populated by the itemID.  I am therefore going to generate a method to do this.

8. In the class which is created, create a new method.  The method must be prefixed with Generate…….

public container generateDescription()
    Container       ret = conNull();
    if (entity.itemId != '')
        target.description = entity.itemId;
        ret = [target.description];
    return ret;

9. Create a FieldGroup on your staging table with the same name as the method you have just created.  Add the fields you wish to pass into the method.


10. Create a new method in the class named getReturnFields.  This tells the migration tool which table and field the value passed back from the the generate method should go.

public static container getReturnFields(Name _entity, MethodName _name)


DataSourceName dataSourceName = queryDataSourceStr(DMFInventItemBarcodeTargetEntity, InventItemBarcode);

Container      con            = [dataSourceName];


Name fieldstrToTargetXML(FieldName _fieldName)


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



switch (_name)



case methodStr(DMFInventItemBarcodeEntityClass, generateDescription) :

con += [fieldstrToTargetXML(fieldStr(InventItemBarcode, Description))];



default :

con = conNull();



return con;


The Import

8. Go to Data Migration Framework –> Setup–> Target Entities.

9. Create a new custom Entity with the objects you have created.


10. Go to Modify Target Mapping and check your fields are mapped correctly.  Although you can change the mapping here, if it is not correct, it is likely there is something missing from your project.


11. You can now go to Data Migration Framework –> Common –> Processing Group and create a new processing group.  Click on Entities and create a new entity for the processing group.

12. Go to Generate Source Mapping and select the fields you are importing and the order you are importing them. Generate Sample File to get the structure required for your data import.  You can add data here and save it locally.


13. Click Finish and enter your source file into the entity record for the processing group.


14. Click Generate Source mapping.

15.  Go back to your processing group and click get Staging Data.  Click OK, Run on AOS and then OK again.

16.  Your data should now be loaded into the staging table.


17. In the processing group, click on Copy Data To target. Select your job ID, click OK, Run on AOS and the OK.

18.  Your  data should now be loaded into your target table.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s