With the release of Dynamics CRM 2013 Online Spring ’14 update and Service Pack 1, Microsoft released the Configuration Migration tool as part of the CRM 2013 SDK update, which can be downloaded here.

The main purpose for the Configuration Migration tool is to migrate configuration data that is usually stored within custom entities from a source master development environment into a package that can be deployed onto a target live environment. The tool can also be used to package up some sample data say for a product add-on to demo how to use it.

The tool can be used with the package deployer tool, which is also part of the SDK, to create a complete deployment package.

More information on the Deployment Packager Tool is available in a previous post here.

How does the Configuration Migration Tool work?

When we run the Configuration Migration tool, we get the option to Create Schema (which is a list of the attributes we are exporting their display name and type), the option Export Data if we’ve already created the schema (useful if while we progress through a project), and the option to Import Data (which takes the schema and data package previously created).

 

Selecting the Create Schema option means that we can specify which server we want to connect to, either On-Premise or Online / Office 365.


Note:
As of writing the Office 365 option seems to be the correct option for logging on to CRM Online in EMEA.

Then we get to specify which CRM Solution we which to export from, obviously selecting the correct solution will narrow down the entities we can select from.

Here we must remember to include any lookup fields to parent entities, along with the parent entity if we want to migrate that data also.


Now we can click on the Save and Export, where we get the option to export the schema along with data, this saves us a process.

We then the option specify where to save the Schema XML file, and the Data ZIP file.

Clicking on Export Data starts the process off.


We can see that the Schema is validated, and then the entities we selected are added to the export set, and finally a like to the file that has been created is at the bottom of the form.

Select the Import Data option from the main menu on a target CRM system, gives us the option to specify where the Data ZIP file is located.

Once we have provided this we can then click Import Data button to start the import process off. We can see that the process appears to be using the CRM Data parse and import routines to import the data.


 
What does the Schema look like?

The Data ZIP file contains both the data in XML format, along with its associated schema XML. Examining the Schema file we can see that the format is fairly simple.


  disableplugins="false"
>
   
     
     
     
     
   

 
  disableplugins="false">
   
     
     
     
     
     
     
     
     
   

 


One thing to note however are the highlighted XML attributes which appear to be on each entity element. It appears that we can manually modify the attribute to deactivate any Plugins that we have registered on the entities as part of the import process, preventing any of our validation or calculations from triggering. The Plugins are then activated after the import has completed.


A code example of how to export and import data via CRM 2013 can be found in another post here, which is useful if we wish to create an automated integration between CRM and another system.

Note: The configuration migration tool isn’t designed for migrating customer data as I have shown in the example.

How do we enable tracing?

We will occasionally get problems that we need to debug, so we can enable tracing within the DataMigrationUtility.exe.config file which is located within the same directory as the Configuration Migration Utility, e.g. C:\CRM-SDK\SDK\Tools\ConfigurationMigration

To enable tracing, we simply set the various setting to Error, Warning, Verbose or All.

   
      
     
     
     
     
     
     
     
   

   
                type="Microsoft.Xrm.Tooling.Connector.DynamicsFileLogTraceListener, Microsoft.Xrm.Tooling.Connector"
          BaseFileName="DataMigrationUtility"
           Location="LocalUserApplicationDirectory"
           />
     
     
   

From the Shared Listeners section we can see that the log files will be created within

C:\Users\\AppData\Roaming\Microsoft\Microsoft Dynamics® CRM Configuration Migration Utility\

E.g. C:\Users\User1\AppData\Roaming\Microsoft\Microsoft Dynamics® CRM Configuration Migration Utility\1.0.0.575

In the log location we will generally get two or three files, DataMigrationUtility.log, ImportDataDetailLog.log and Login_ErrorLog.log, which contain any tracing details we have enabled.

Hopefully that gives a good overview of how the configuration migration utility can be used.

@simonjen1