Don’t Merge Your Forms in CRM 2013

If you have been using Dynamics CRM before the 2013 version was released, you may have something in your system called “information forms”. This is not a very descriptive term for them, since of course all the entity forms are about presenting “information” to the end user. These forms actually date back to a time in the Dynamics CRM platform history when there was only a single form available per entity. Times have changed quite a lot since then, as entities can now have role based forms, mobile forms, quick create forms and quick view forms.

Although not a specific form type in itself, CRM 2013 introduced a whole new layout for the default entity forms as a part of the UI refresh. Instead of the traditional & boring two column layout, the new CRM 2013 forms are made up of three columns that can consist of not just entity fields but also related entity subgrids, the social pane, Bing Maps component and other exciting new features. Whereas the old default forms were called “Information”, the names of these new forms follow the entity names. So, the account entity will have a new form labelled “Account”, as an example. (By the way: check this tip for optimizing your form naming convention.)

Merge Forms Feature

Since the new forms are designed to make better use of the new navigation paradigm of CRM 2013 as well as present the data in a much richer way than the old “ERP style” forms of past CRM versions, customers who are upgrading their Dynamics CRM deployment to the latest version are advised to migrate into using these new forms. In fact, Microsoft has stated that the next major version (CRM 2015) would no longer support the use of the old “information forms”.

To make this transition easier, Microsoft has provided a feature called “Merge Forms”. This new button available on the form editor in the CRM customization UI (which still utilizes the old CRM 2011 style layout even in CRM 2015, by the way) is intended to be used for bringing the tabs, sections and fields from your old forms onto the new forms with as little clicks as possible.

The process is described in the article “Update your forms to Microsoft Dynamics CRM 2013 or Microsoft Dynamics CRM Online Fall ’13”. Even more detailed steps can be found from the PDF document “How to Prepare for the CRM Online Fall ’13 Service Update”. Basically what the feature does is bring in the contents of the old form to the end of the currently open form, with the intention of making it faster to rearrange your customized fields and sections to align with the new default form’s content and layout.

Sounds like a handy feature, right? There’s only one slight problem with it: it doesn’t work.

Conflicting ID Values

“What do you mean it doesn’t work? I have used the button to bring in my custom fields and it did just what I expected.” Well, maybe I should rather say that it works partially. If you never export your CRM customizations into a solution file and move it to a different environment, you may not notice that anything is wrong with your forms. However, if you do want to move the customizations between development, test and production organizations, you might run into the below error message during the solution import process.

After the error, if you download the log file and open it, you’ll see a message like this:

Error code 0x8004F658. The label ‘E-mail 2′, id: ’87dc7c9c-94c1-3953-e490-11413b31d0ad’ already exists. Supply unique labelid values.

What the system is telling us is that we’re trying to insert an item into the customization metadata that has a non-unique ID. Depending on the scenario, the item could be a field or section label. But how did the ID end up being a duplicate? After all, we don’t assign these GUID values in the customization UI, rather the CRM platform generates them. What could have caused the system to violate its own rules?

The answer can be found from this thread on the MSDN forums: CRM 2013 Solution Import. A Microsoft support engineer has confirmed that the error is caused by a design mistake in the Merge Forms feature. Apparently in the process of merging form content from the old form onto the new one there is more data carried over than is needed. Not only do you get the form components exactly the way they are configured in the original form, but you also get the same ID’s. Now, since the old form also exists in the system, this will cause an error message when you try to import your solution file from the source system to the target environment, like from development to test environment, for example.

The Workaround

The system where I ran into this problem was running Dynamics CRM 2013 Service Pack 1 (6.1.0.581) with no Update Rollups (see this earlier blog post for help on understanding the different updates and version numbering). The forum thread above does not indicate that a hotfix for the form merge bug would have been included in one of the released updates so far, so I’m assuming that all CRM 2013 environments are affected by it during the time of writing.

The suggested workaround in the forum discussion was basically “start all over”, meaning removing the merged content from the form and re-adding the components back there one by one. In the environment I was working on this would have required many hours of work with using the form editor on a number of entities , which I wasn’t too keen on spending there. I had just migrated a copy of the CRM 2011 production organization database onto a CRM 2013 test server and was in the process of testing the upgrade steps before the final go-live, so re-doing the customizations at this stage just sounded like both a schedule challenge as well as a potential source for new issues.

I extracted the CRM solution zip file and poked around the customization.xml file for a while, trying to think of a way out of this situation. After I realized that trying to edit the XML manually would only land me into a deeper hole, it occurred to me that there was another feature in CRM that performed something similar than the broken Merge Forms: the “Save As” button. Copying entity forms to create new variations was something that I had used many times with no issues, so perhaps I could rely on it here as well?

I proceeded with creating a copy of each of the entity forms where I had used the Merge Forms feature. Since the new form versions created via “Save As” are able to co-exist with the original forms without causing any conflicts, this must mean that the CRM platform assigns the required new ID’s to the form components. Based on this reasoning, I therefore assumed that once I deleted the original merged form and renamed the new copy (as well as configured the form order and security roles), I would have a clean solution file with unique ID values. After testing the solution import I was extremely glad to see that this was in fact the case, as no more error messages appeared during the import. Saved by the “Save As”!

Don’t Just Merge – Design

So, with the above workaround and a potential upcoming hotfix, is there any reason not to use the Merge Forms feature? In my humble opinion, the merge process is not a best practice but rather just a quick’n dirty way of getting the custom fields to appear on the entity forms. If you don’t in practice know how to customize your Dynamics CRM environment but need to cope with the updated UI of the new version, then the merge will technically make it possible to keep using your CRM data. What it will not do is produce a system that your end users will enjoy.

The merge will bring over a lot of duplicate content (all the default fields) that you may forget to clean away from the new form. It will also create very confusing components for the system administrators, such as the old “What’s New” section vs. the new Social Pane, which require a deeper understanding of the Dynamics CRM platform evolution to really figure out. The biggest risk is that the form content designed for the old version UI will end up living alongside the content that is specifically made for the post CRM 2013 world, creating a disconnected and illogical application that works differently depending on the area where the user navigates to.

Instead of taking the shortcut and doing a quick content merge, I recommend investing a bit more time and effort in planning what’s the best way to present the data and how to make it as easy as possible for the users to interact with it through the UI. If you need some ideas for improving the user experience of your Microsoft Dynamics CRM environment, take a look at my previous post that listed 10 tips for designing a great user experience in Dynamics CRM.