In this post, I will be discussing the scenarios related to table/Field mapping during Microsoft Dynamics AX 2012 Data upgrade. Table mapping is one of the key steps which involves in any successful data upgrade and requires special consideration in the scenario where the Source Dynamics AX environment is highly customized.

To perform Table mapping click System administration > Setup > Checklists > Data upgrade checklist. Click Generate table mappings.


This will open the form which attempts to map tables and fields from your Microsoft Dynamics AX source system database to target tables and fields in the target database. The results are displayed so that you can resolve any errors that occur. You can rerun the form as many times as necessary until the mapping completes successfully.

Table mapping form

The upgrade framework uses the mapping algorithm to map the source and target tables and fields which is as follow:

Source and target table mapping algorithm:

During data upgrade the mapping algorithm follows the following precedence for source and target table mapping:

  1. Check special mapping – this is custom mapping as defined within pre-synchronize scripts
  1. Try to map by name, e.g. SalesLine -> SalesLine (Salesline table exist on both source and target system)
  1. Try map by DEL_ prefix, e.g. SalesLine -> DEL_SalesLine (salesline table on traget doesn’t exist but DEL_Salesline table exists)
  1. Try to map by ID (Salesline or DEL_salesline table on target doesn’t exist but the ID of the Salesline table on source and target is same)
  1. Otherwise, mapping error is reported and must be fixed!

What is Special Mapping – Custom mapping:

The special mapping is basically the custom mapping which is defined within the pre-synchronize  scripts as the custom script, these mapping scripts are written to handle mostly the modifications or customizations in the data dictionary objects or to define mapping for any new data object i.e. table or field

During the upgrade, mapping between Dynamics AX 4.0 or AX 2009 and Dynamics AX 2012, if you want to ignore individual fields in a table you want to upgrade, you will need to either

  1. Keep the unused fields in the tables and rename them as DEL_ and assign them to the SYSDeletedObjects60 Configuration Key (the recommended approach) OR
  2. Drop the fields from the table and add a PreSynch upgrade script to AX2012 that uses a Bulk Copy command using the DoNotCopy option for each field. See the updateMappingCompanyInfo method of the ReleaseUpdateDB60_Administration class for an example:

This method below can be considered for demonstration purpose:

UpgradeScriptTableAttribute(‘CompanyInfo’,false, false,false, false)
void updateMappingCompanyInfo()


The above is the standard Pre-Sync script script in which two custom mapping scenarios are being covered :

  1. AddFieldNameMapping : First scenario is if there is some field in Source AX 4.0 or AX 2009 which is required to be mapped to the target AX 2012 field. This mapping is done by AddFieldNameMapping method. this method takes following parameters:
    • addFieldNameMapping(TableName oldTableName, FieldName oldFieldName, TableName newTableName, FieldName newFieldName, NoYes _system = NoYes::No)
      • <param name=”_oldTableName”> –> The source table name.
      • <param name=”_oldFieldName”> –>  The source field name.
      • <param name=”_newTableName”> –> The target table name.
      • <param name=”_newFieldName”> –> The target field name.
      • <param name=”_system”> –> Indicates whether the record has system mapping.
  2. AddBulkCopyFieldOption : The other scenario if it is required to not copy a particular field.this mapping is done by addBulkCopyFieldOption method. This method takes following parameters:
    • addBulkCopyFieldOption(str _tableName, str _fieldName, ReleaseUpdateBulkCopyFieldOption _fieldOptions, boolean skipValidate = false
      • <param name=”_tableName“> –> The source table name.
      • <param name=”_fieldName“> –>  The source field name.
      • <param name=”_fieldOptions“> –>  The possible three options i.e. DoNotCopy, LTrimTarget, None :


Adding the code to that method would only run during the Pre-Synchronize phase, and would not execute until your next test run. If you want to have the changes take effect after running the Pre-Synch scripts, put the same commands into a Job and run the job and then execute the Generate table mappings step again. You can rerun the table mapping again and again until all the errors are resolved.

If you don’t care about the whole table, it is recommended to rename the table DEL_XXX and assign them to the SYSDeletedObjects60 Configuration Key, but if you truly don’t care about the data, you can just allow the mapping error to occur and have it not copy the table over.

Leave a Reply

Recent Comments