Importing Microsoft Dynamics CRM Customizations / Solutions Gotchas 101

One of the great features about Microsoft Dynamics CRM, is the ability to build a solution based on the CRM / XRM platform, and then export / import those customizations to another CRM deployment. We see this process quite often when it comes to ISV solutions, accelerators, or other custom developed solutions. Most times this works without issue, and you are up and running with the new solution fairly quickly. 

Unfortunately there are times, where the export / import customizations facility can cause problems for any CRM / XRM environment. The CRM XML customization files basically work on a delta premise, meaning that when imported, CRM will attempt to process the delta between what is currently in CRM and what is in the customization file. This means that the addition new entities, attributes, or relationships to the customization file will get created in CRM. This principle is simple and works well. 

Problems start to arise, when the item that is changed in the customization file already exists in CRM. For example, say you are working with an ISV that has added a timer control to the case entity that allows you to track the time spent on cases. As part of this solution, the ISV has made changes to the “Satisfaction” pick-list within CRM, adding new values and changing other values. In addition to the various pick-list and attribute changes, the customizations also include updated views, an updated main form, and custom JavaScript on the forms events. If you were to simply import these customizations, the net outcome would be:

The above bullet listing doesn’t sound too bad at first glance. However as you start thinking about the details around each of those items above; you start to see how big of a problem this can become. For example if your form gets overwritten, this doesn’t just mean that you have to fix missing attributes and their layout, it also means that any JavaScript that you have included on the form will also get overwritten. For some, this could be a huge problem. When it comes to modifications to pick-list values, this not only affects the choices that your users have for values in CRM, but it can have an impact (if temporary) on your existing data. Since CRM stores the pick-list selections as the index number of the selection and not the absolute string value, this causes the label change to cascade all the existing data in CRM for that specific attribute and value. This can easily be fixed by changing the label back to its original value, but if it is overlooked you will now have a data problem where some records point to the old meaning of the value and some point to the new meaning of the value. Like the form changes, this could be a huge problem for some environments. 

These problems occur in CRM because the import facility does not account for individual changes to the following types of information:

Instead it looks at the above items as a whole and simply overwrites the existing data that exists in CRM. With all of the above being said, it is extremely important to always have a backup of your customizations, and to test the import of new customizations in a non-production environment. Fortunately Microsoft and other ISVs have acknowledged this shortcoming with CRM, and have not relied solely on the customization file to bring in new CRM configurations. For example the eService Accelerator (available from Microsoft) takes an intelligent approach when updating CRM with the new fields, pick-list values, and JavaScript code. Instead of simply importing the customization xml directly into CRM, it goes ahead and merges this new xml with your existing xml and then imports that back into CRM. Through this process Microsoft avoids creating conflicts with your existing system. Other ISV solutions like ExactTarget take actually use the CRM MetaData service to add its new attributes and values pragmatically. The approach these solutions take should avoid any conflicts with your system; however it is still extremely important to have a backup of your customizations and to also do a test import on a non-production system.

For scenarios where you are only provided with the xml for the new customizations, I would recommend using a compare utility to examine the changes of the new file and how they might impact your current configuration. Microsoft has recently released such a utility via the CRM SDK, and it can be downloaded from the following link: http://msdn.microsoft.com/en-us/library/dd442453.aspx. It is important to note, that this is not the compiled application and is simply the source code for the application. As a result, you will still need to open and build the solution in Visual Studio. It is important to note that this utility will not resolve any conflicts between the two xml configurations, however it will allow you to visually step through each CRM / XRM entity and examine what changes will occur. At that point it is up to you to manually handle the updates to CRM. One good rule of thumb that can typically be used would be to first import the new xml into your non-production environment allowing your current customizations to get overwritten. Once finished, re-import the backup of your production customizations. This will restore the CRM forms, views, and pick-lists to their original state, while also maintaining any new relationships and attributes that were previously added via the new customization file. After this process you will have to circle back and use the compare utility to manually add any form changes, view change, or pick-list changes that are needed for the new customizations. Although this is manual, it does give you full control of the resulting outcome of the newly imported customizations.

In summary, be very careful when importing external customizations into CRM. It may seem harmless at first, but it can create a situation that could be very difficult to recover from. Please feel free to post a reply to this blog entry if you have encountered such a problem. Making others aware of a potential problem with a custom solution only helps to strengthen the community that is CRM. 'Til next time.

When it comes to importing CRM / XRM customizations from other sources, you must take caution and first test the import in a non-production environment.