With Unified Service Desk for Microsoft Dynamics 365 you will want to migrate your configuration from say development to production. Recently there have been some changes in this area, so in this post I will describe the process and offer some tips along the way.

Tip: If you would like to skip to what has changed, just read the prerequisites section of this post!

The concept of moving “software” from one server (or in our case Dynamics 365 organisation) is simple enough. Often you will have a three system scenario. Developers will make changes in the development server, tester (or the business) will check these changes on a user acceptance server and then finally we have the live production environment. Because of this moving the USD configuration from one environment to another is going to be an important and essential step.

Keep in mind that the USD configuration is a little different to “normal software”. As it is simply data you are moving from organisation to another. We therefore need to use the “Configuration Migration Tool” provided by Microsoft. (More on that soon!)

In this post I will explain, any prerequisites, how to export the configuration and how to import it. Additionally I will mention a few tips along the way. (Some things I have found from experience that are worth watching out for.)

Prerequisites

Note: If you have previously been migrating your configuration from organisation to organisation without any issue and suddenly you can’t the reason might be that you need to download a new version of the configuration migration tool. I will explain the revised process for this below.

Before you can export or import your USD configuration you will need to download the configuration migration tool. Recently Microsoft made some changes to the authentication process, meaning if you have an old copy of this tool you will find it no longer connects to newer V9.0 Dynamics 365 instances. (Basically the October 2017 release onwards.)

You will find the migration tool in the Developer Guide (formerly known as Dynamics 365 SDK.). Recently the approach to the SDK has also been changed! No longer do we download the entire SDK. Instead it is accessed online as the Developer Guide. You will find the Developers Guide at this location (As a Dynamics 365 developer you may want this in your favourites!) ;

https://docs.microsoft.com/en-gb/dynamics365/customer-engagement/developer/developer-guide

Within the Developer Guide you will find a really useful section on Unified Service Desk. (Something else I suggest you add to your favourites!) The link to access that directly is shown below;

https://docs.microsoft.com/en-gb/dynamics365/customer-engagement/unified-service-desk/unified-service-desk

Before we start we need the migration tool. In the Developer Guide you will find a section called “Additional resources” and within that you’ll find an option headed “Tools on NuGet”. You can access this page directly here.

The tools available include;

• Code generation tool
  
• Configuration migration tool
  
• Package deployer
  
• Plug-in registration tool
  
• SolutionPackager tool
  

Right now we are only interested in the migration tool but you might as well download all of the tools. You might need them later!

The new process to extract the tools is documented on the “Download tools from NuGet” page. It is simply a case of loading PowerShell, changing directory to the target location and then running the script provided. (Just copy and paste it into PowerShell!)

In my case I wanted the tools in my documents directory, so you can see below that I have loaded PowerShell and typed “cd c:\users\neilp\documents”.

Having done this I pasted in the script provided and pressed enter. A few seconds later a directory called “tools” was created. You will find the configuration migration tool in this directory.

Export Configuration

Now you have the migration tool you will need the default XML schema definition for the entities that make up your USD configuration (USDDefaultSchema.xml).

Microsoft’s guide on exporting the USD configuration can be found here.

The process to find the schema file is to download the SDK!! You can find that page here. When you run the download you will only need the “MicrosoftDynamicsCRM2016UII.exe” file.

Once downloaded extract the contents. You will then find the “USDDeafultSchema.XML” in a folder called “USD Develeoper Assets\USD Configuration Tool Schema”

Before we start …. You may need to be aware that the Schema does not include the notes entity. The reason being that the migration tool does not filter the data exported! Meaning if it tried to export notes all the notes in your entire organisation would be exported. Why do I mention this? It is important because if you use customization.zip files in your configuration these are actually stored as attachments on notes. So they aren’t going to get exported. You will need to migrate these manually.

The process to use the schema and migration tool is documented below;

Step One: Load the migration tool. Simply open the Configuration Migration tool, locate the “DataMigrationUtilty” application and run it.

Step Two: Select the export option and click continue.

Step Three: Login

Tip: A useful tip at this stage is to ALWAYS select the “Display list of available organizations”. If you don’t your default organization will be selected. That is typically going to mean your production environment and may not be the one you want!!

Step Four: If you ticketed the display available organizations option, pick your organization.

Step Five: Enter Schema and data file names.

Select the USDDefaultSchema.xml file you downloaded and define the name of the data file to export. (The default is data.zip!) When ready click “Export Data”.

Step Six: Wait for the export to run!

There will now be a pause whilst your configuration is exported to the data file. Once completed you can click Exit.

Your data.zip file will now be ready to import into another organisation. See details below.

Import Configuration

Before I describe the import process it might be worth considering what the migration tool will actually do! It is “simply” exporting data from one organisation and importing into another. If you think about that, it implies it will only insert or update data records. No data is removed.

The fact that data isn’t removed actually presents a challenge. Say you want to delete a load of actions that are no longer required, the migration tool will not do this.

Additionally when it updates a record it will need to uniquely find the record to update. This seems to be typically done using a combination of “order” and “name”. You need to be aware of this as changing the order or name of things can result in unexpected duplicates.

For this reason I often delete the existing configuration before I import a new one. You can simply do this by selecting all of your hosted controls (etc) and clicking delete. I will often open and delete everything from each USD option in turn, so hosted controls, actions, scriplets etc etc.

Tip: For hopefully obvious reasons, it is a good practice to export a copy of your existing configuration before you remove it!

The one I often skip is the configuration option. As removing that will remove the configuration from all the associated users. I typically don’t want to do that!

Tip: If you take this approach, be aware that “agent script answers” and “toolbar buttons” are two entities that won’t get cleared. As far as I can tell the out of the box cascade rules do not delete these when their parent record is removed. To get round this, you can use advanced find to open these entities and remove from there.

The steps for the import are as follows;

Step One: Load the migration tool. Simply open the Configuration Migration tool, locate the “DataMigrationUtilty” application and run it.

Step Two: Select the import data option and click continue.

Step Three: Login.

Tip: A useful tip at this stage is to ALWAYS select the “Display list of available organizations”. If you don’t your default organization will be selected. That is typically going to mean your production environment and may not be the one you want!!

Step Four: If you ticketed the display available organizations option, pick your organization.

Step Five: Select the zip file you need to import. Then click import.

Step Six: Wait for the import to run! Then click Exit.

You import should now be completed and the configuration migrated. One tip I have at this point is to do something I always do! And that is to check the row count on all of my hosted controls, actions, etc. As I like to be confident the import was 100% successful. I therefore like to check the number of rows in my source organization with the row count in my target. Granted this might be unnecessary! But it does give me confidence everything is good.

Something else that might be useful to know is that the migration tool exports all of the rows in a given entity, this includes all active and inactive records. So you might want to check inactive records as well as active.

I hope this post will have helped people understand the migration process and how it has recently changed. The first time I did this the steps involved felt quite complicated. But after a few times it does become a routine and simple process.