In my previous blog post, I outlined the Case for Microsoft Dynamics CRM Unified Service Desk (USD). The project in that post has entered its second phase with the third phase fast approaching. As critical with any project, the project has well-defined and executed Software Development Lifecycle (SDLC) ensuring USD releases take the appropriate precautions. The SDLC process we defined takes the regular builds from Development and pushes to Test, User Acceptance Testing, and Production. We use Visual Studio Team Foundation (TFS) for source control and build management. The process we defined is repeatable, reliable and well adopted.

Deploying USD

As we released the project builds, we relied on the Microsoft migration utility which greatly helps deploy the USD configuration. If you are not familiar with this utility, it is similar to the Dynamics CRM Solution export/import process used to move Dynamics CRM customizations but is capable of moving the USD metadata USD from environment to environment. Unlike a CRM solution file, importing a USD solution does not perform any schema changes. USD solution imports only metadata.

Like the native CRM solution deployment process, the migration utility is non-destructive and only performs creates and updates. Deletes need to be done manually. Manual deletes are manageable if the changes are minimal. However, the project we are working on has multiple people making regular changes. In a perfect world, each person would document their changes and that document would be turned into a change management release document for operations to follow during the release to production. Realistically, with big goals and tight timelines, steps are accidentally skipped or forgotten. Realizing this, we looked to make the migration utility part of the regular SDLC. For this to happen, we had to resolve a couple of issues.

USD Schema

Unless specified otherwise, the migration utility uses the primary attribute (name) of each entity to check to see if the record already exists in the destination system. In our experience, this is not a reliable value to check. Hosted controls, actions, scriptlets, and events have been renamed, so using this as the import key caused a lot of duplicates and a deployment process we cannot rely on.

To resolve the duplicate records, Celedon Partners (CP) updated the schema configuration to use the primary key (ID) of each entity rather than using the default value of the name. This ensures that if you update the name, the migration utility will perform the update if it finds the GUID or creates the record if it doesn’t. Like the CRM solution file, the GUIDs for the records are kept from environment to environment making them a reliable key.

To update the schema to use the primary key of each entity:

  1. Open the migration utility
  2. Select solution ‘Dynamics Unified Service Desk’
  3. Click ‘Add All’ to include all the entities
  4. Remove User and User Settings entities
  5. Click on Tools and then Configure Import Settings

Configuration Migration Utility


For each of the following entities, add the related primary key to the “Fields to compare on update”:

Entity Attribute Name Attribute Schema Name
Action Call Agent Script Action msdynusd_agentscriptactionid
Agent Script Task Task msdynusd_taskid
Entity Search Entity Search msdynusd_entitysearchid
Event UII Event msdynusd_uiieventid
Scriptlet Scriptlet msdynusd_scriptletid
Toolbar Toolbar msdynusd_toolbarstripid
ToolbarButton ToolbarButton msdynusd_toolbarbuttonid
UII Action UII Action uii_actionid
UII Hosted Control UII Hosted Control uii_hostedapplicationId
UII Non-Hosted Control UII Non-Hosted Control uii_nonhostedcontrolid
Windows Navigation Rule Windows Route msdynusd_windowsrouteid

Your USD solution may require additional entities.

Cleaning up USD Configuration

What happens if you have an environment that’s a mess? Cleaning it up manually is time-consuming and error-prone. Since the USD configuration is all metadata, we decided to remove all USD related metadata and re-import into a clean system. CP created a SQL Server Integration Service (SSIS) package to retrieve and delete the USD metadata from CRM. There are roughly 30 to 40 USD entities. Fortunately, many have parental relationships which means that you can start with the parent and it will cascade delete. This limited the number of entities to about 10. After executing the SSIS package, all the USD metadata was removed, but the configuration (users, schemas, views, etc.) remained intact. Once deleted, we re-imported the USD configuration into the environment without any challenges.


We performed system and functional testing extensively after the deployment and everything appeared that the deployment was a success. Give our previous deployment challenges we wanted to take one additional step to verify. CP developed a SSIS solution to retrieve the USD metadata and store in a local SQL environment. SQL scripts compared the source and destination USD data. Using the SQL output, we were able to perform an additional analysis looking for deltas. For example, were all the hosted controls populated? If so, were all the lookups for those hosted controls also populated properly? This level of validation helps ensure that the complex relationships and values moved from one environment to another successfully. For our solution, we compared the source and destination values of the following entities:

  • Action Call
  • Agent Script Actions
  • Entity Search
  • Hosted Controls
  • Scriptlet
  • Subaction Calls
  • Toolbar
  • Toolbar Button
  • Toolbar Script Agents
  • UII Action
  • UII Events
  • UII Event Actions
  • Window Navigation Rules

I prefer SQL to do my analysis, but exporting using CRM Advanced Find and Excel can provide similar results.


Deploying CRM USD is no more or less complex than any other solution. Learning how to troubleshoot and validate a deployment and following a process that is reliable and repeatable is the key to success. The extra steps we have taken may seem redundant or overkill, but this is how the project team ensures that a deployment was successful. With 800 CSRs using USD, it is critical that we have absolute confidence in the deployment process. Although we have built these processes to help, they do not replace a solid and disciplined team that follows the SDLC.

Happy USD-ing!

Chris Scott

A couple of great resources: