I often work with Unified Service Desk for Dynamics 365, having created a “solution” in my development environment I will obviously need to migrate it into a test or production instance. The process we use for this is quite straight forward, as Microsoft’s configuration migration tool can be leveraged to export and import my config. However I have always found migration of my customization files more difficult, until now!

The Problem

To explain, customization files in Unified Service Desk are used to deploy executable code to the desktop. This is achieved by the creation of a zip file that is cached to the local client. The zip file is attached to the customizations entity as a note! In the past this has presented a challenge …. As the configuration migration tool always extracted all of the rows in an entity. So I either exported no notes or every note in the system. Meaning I had a choice to either manually attach the customization zip files or I had could “hack” around removing all of the unwanted notes from my exported configuration. Neither of these options was ideal!

The solution

The configuration migration tool can also filter records using a fetchxml query. Meaning we can extract only the notes associated with the customizations entity rather than all of the notes.

Microsoft do ship a schema we can use with the configuration migration tool to export the USD entities. I don’t believe that includes the notes entity, so in this post I will explain how to update your USD schema to include a filtered version of the notes entity.

Tip:
Whilst this post is written in the context of Unified Service Desk you may be using the configuration migration tool to move other data. If so, this filtering approach could be adopted on other entities as required!

Download tools

I believe an updated version of the configuration migration tool became available around Dec 2019. Because of this, if your are using an older copy of the configuration migration tool you may need to install the latest version.

You can download the common data service tools using PowerShell by following the link below.

https://docs.microsoft.com/en-gb/powerapps/developer/common-data-service/download-tools-nuget

It is a simple process, you’ll just run the provided PowerShell script and a few seconds later the tools will be ready.

SPOLIER ALERT: If you are feeling really lazy …. skip to the conclusion at the end of this post. As I give you the ability to download the schema I created!!

Create schema

Once you have the latest version of the CDS tools available you’ll want to edit the schema you are using to include the notes edit. The approach I take is to generate a new (“temporary”) schema file containing just the notes entity. I then code the XML for that into the end of my existing schema file.

Luckily you don’t need to know how to craft XML code to complete this task! As the configuration tool includes an option to generate your schema.

First locate the configuration migration application in the tools you extracted. And run the “DataMigrationUntility” application.

When I first run the configuration migration tool I select the “Create schema” option and click continue.

The next step will be to login into your Dynamics 365 environment. (Notice that I have ticked the “Display list of available organizations” option!)

Once you have authenticated you will need to select the required instance.

Now I select my notes entity and in my case all of its fields. You first select a solution and then your entity.

Tip: It is possible to do as I did and stick with the Default solution but selecting a smaller solution may prove an easier approach to find the entity you want to include in your schema!

The next stage will be to enter the FetchXml I want to use to filter the notes to be migrated. So before I do anything I will need some FetchXml! I like to keep my life simple, so I didn’t try to write my code from scratch. I used Advanced Find to generate my Fetch command!

Below you can see that I have created an advanced find that returns all notes that are linked to an active customization file.

You can see below that I have opened the resulting FetchXML in Notepad.

Tip: We will come back to this in a minute as our Fetch will need some edits!

Now back in configuration migration tool I and use the “Configure Import Settings” option to add my FetchXml into my export schema. You can find the required option in the “Tools” menu. (As shown below.)

Within the “Configure Import Settings” option I select the “Use FetahcXMl to filter record option.

Below I have simply pasted in the FetchXML from my advanced find. I have done this to show you the error you will see! As the FetchXML will need some changes.

Before you add your FetchXml you need to remove the output-format statement, all attributes and any order clauses. (As highlighted below)

The resulting FetchXML (shown below) will not give an error.

I am now ready to use the save and export option to save my schema. Having clicked “Save and Export” I simply give my schema a name.

Tip:
At this stage, when asked if I want to export the data I clicked No. As I didn’t need that!

Create a new USD Schema

I now have a “temporary” schema that includes just the notes entity. (With the required filtering.)

The next stage is simple enough. Just open the xml file you created. Copy the code for the notes entity and insert it into the end of your existing schema for Unified Service Desk.

Tip:
You will only copy the code between the “<entities>” tags. As you’ll need to avoid having a duplicate <entities> section in your result schema.

Conclusion

Below I have included a link to the schema I now use for exporting my Unified Service Desk configuration. It includes a filtered version of the notes entity! (You could just use that and save your self the effort of following the steps above.)

Tip: This file is a zip file as I couldn’t upload an xml directly into WordPress! You will need to download it and extract the contents. (Sorry!)

NEILS_USDExportSchema_V7

Now you have a new schema you are ready to use the configuration migration tool to export your USD config ready for import into your production system.

Enjoy!