A frequent challenge when working with Dynamics CRM is making sure that configuration data like teams and queues have the same record GUIDs in all of a project's different environments for development, testing and production.
Without identical GUIDs, any processes, scripts or other customizations that reference a record's id will have to be changed between environments, and this is risky because it means you're running a solution in production that's different than what was actually tested in a lower environment.
In the past I've used a few different open source tools for keeping record GUIDs in sync, but I never liked any of them, so I decided to build my own. I call it the Alexander Development Dynamics CRM Configuration Data Mover.
The Dynamics CRM Configuration Data Mover is based on the idea of a single job with multiple steps. There are certain job-level parameters (source organization, target organization, etc.), and each step has a FetchXML query for the records and attributes to be retrieved from the source system and transferred to the target system. The tool also allows a job to be saved to an XML file so it can be reloaded later.
When you first open the tool, it looks like this.
The way the tool works is that it first sets up any GUID mappings, and then it loops through each job step. It executes each step's specified FetchXML to retrieve the set of records to transfer. It loops through each record and tries to update an existing record with the corresponding GUID in the target system. If it cannot find an existing record to update, it creates a new one with correct GUID.
Here's a screenshot of the GUI with a job fully defined.
Here's an explanation of the various settings and parameters:
- Source - Simplified CRM connection string for source organization.
- Target - Simplified CRM connection string for target organization.
- Save connection details? - If checked, connection details should be saved in configuration file. Note, connection details are unencrypted.
- Map root business unit GUID? - If checked, the job will automatically change any GUID references from the source organization root business unit to the target organization root business unit.
- Map base currency GUID? - If checked, the job will automatically change any GUID references from the source organization base currency to the target organization base currency.
- Job steps - A list of steps for each distinct entity transfer operation.
- Step name - Sets the name of the selected job step. The step name is used in logging outputs.
- Step FetchXML query - The FetchXML query that determines which records and specific attributes will be transfered.
- Update-only step? - If checked, the step will not attempt a create operation if the update attempt fails.
- GUID mappings - List of GUIDs in the source organization that will be replaced with GUIDs in the target organization.
There a few things to keep in mind when using the Dynamics CRM Configuration Data Mover:
- Absolutely no validations are performed against the FetchXML. If something is wrong, the error won't show up until a job is executed.
- Following up on the previous point, if you include an attribute in the query that you aren't able to update in the target, the tool won't know any better, and you will get an error when the job is executed.
- Because only the attributes included in the FetchXML query are used for updating/creating a record in the target system, you can sequence record creation and update steps by using different FetchXML queries in different steps.
To elaborate on that last point, it's similar to how you have to structure an import for accounts and contacts into CRM. You have to import the account first without a primary contact, then create the contact and set its parent company to the account before finally updating the account to set its primary contact. You probably won't be using accounts and contacts as configuration data, but I've seen lots of situations in the past where there are cross-references like this between configuration data entities.
Command line interface
I've also built a separate command line tool that can execute a job from a file generated by the GUI tool so that configuration data transfers can be automated. This would be useful if you have a single "gold" organization that contains configuration data and you want to automatically push out updates to all of your other organizations.
One thing worth noting is that if you specify source and target connections as parameters at runtime, those values will override anything stored in the job's configuration file.
Here's the command line tool running a job:
The Dynamics CRM Configuration Data Mover uses the Apache log4net library for logging. The GUI and CLI versions each generate two log files:
- ConfigDataMover.log - This is a verbose log of each step in the process. Its contents resemble the output in the CLI tool screenshot above.
- RecordError.log - This logs only the GUID and logical name for each record that cannot be transferred so it's easier to find and fix issues.
Here's a row from the RecordError.log file that shows a team record that could not be transferred because the GUID for the source administratorid did not exist in the target organization.
2015-11-10 09:34:50,910 RECORD ERROR: 58ef627a-1787-e511-941e-08002751dfcb, team
You can modify the format of the logs by updating the log4net configuration in the app.config files. An overview of logging configuration options can be found here.
Getting the Dynamics CRM Configuration Data Mover
The source code is available in my GitHub repository here.
A compiled version can be downloaded here.