File Migration in Unified Service Desk for Dynamics 365

Migrating solutions in Unified Service Desk (USD) for Dynamics 365 can be pretty straightforward, thanks to Microsoft’s configuration migration tool. However, migrating customization files has always been a tricky part—until now. After grappling with this challenge myself, I’ve found an efficient solution using the tool's filtering capabilities with FetchXML. Here’s how you can simplify this process too.

The Challenge: Migrating Customization Files

Customization files in USD are vital for deploying executable code to desktops. These files are packaged in a zip file and attached to the customizations entity as a note. The problem arises when migrating these files using the configuration migration tool, which typically extracts all notes in an entity. This leaves you with the choice of manually attaching each customization file or tediously filtering through unwanted notes—a frustrating and time-consuming process.

The Solution: Using FetchXML Filtering

The key to overcoming this challenge lies in filtering records using a FetchXML query within the configuration migration tool. By doing this, you can extract only the notes linked to the customizations entity, streamlining the migration process. Although Microsoft provides a schema for USD entities, it usually doesn’t include the notes entity. Below, I’ll show you how to modify your schema to include these filtered notes.

Pro Tip. While this guide focuses on USD, the FetchXML filtering approach can be applied to other entities as well.

Step 1. Download the Latest Tools

Start by ensuring you have the latest version of the configuration migration tool, released around December 2019. If you’re using an older version, upgrade it by downloading the Common Data Service (CDS) tools via PowerShell from the [official guide](https://docs.microsoft.com/en-gb/powerapps/developer/common-data-service/download-tools-nuget). Running the provided script will have you ready in seconds.

Step 2. Customize Your Schema

With the tools in place, follow these steps to create a schema that includes the filtered notes entity:

Generate a Temporary Schema

• Run the `DataMigrationUtility` application and choose “Create schema.”
• Log in to your Dynamics 365 environment and select the required instance.
• Choose the notes entity and all its fields.
  
  

Create FetchXML

• Use Advanced Find in Dynamics 365 to generate a FetchXML query that returns notes linked to active customization files.
• Open the generated FetchXML in Notepad for minor edits. Below here is the FetchXML Code.

  <fetch version="1.0" output-format="xml-platform" mapping="logical" distinct="false">
    <entity name="annotation">
      <attribute name="subject" />
      <attribute name="notetext" />
      <attribute name="filename" />
      <attribute name="annotationid" />
      <order attribute="subject" descending="false" />
      <link-entity name="msdyusd_customizationfiles" from="msdyusd_customizationfilesid" to="objectid" link-type="inner" alias="customFiles">
        <filter type="and">
          <condition attribute="statecode" operator="eq" value="0" />
          <!-- Add additional conditions if needed -->
        </filter>
      </link-entity>
    </entity>
  </fetch>

Refine FetchXML in the Tool

• In the configuration migration tool, select “Configure Import Settings” from the “Tools” menu.
• Paste your FetchXML, removing the `output-format` statement, attributes, and order clauses to avoid errors.
  

Save and Export Your Schema

Once your FetchXML is properly formatted, save and export your schema. Skip the data export if unnecessary.

Step 3. Integrate with Your USD Schema

Finally, integrate this filtered notes schema into your existing USD schema.

• Open the temporary schema file you created.
• Copy the notes entity code between the `<entities>` tags.
• Paste this code into the end of your existing USD schema, avoiding any duplicate `<entities>` sections.

Conclusion

You now have a customized schema that includes only the filtered notes entity, making USD customization file migration much more efficient. With this schema, you can easily export your USD configuration and import it into your production system without the usual headaches.

Quick Tip. I’ve included a download link for the schema I now use, packaged as a zip file for your convenience. Just download and extract, and you’re all set!

By following these steps, you’ll find migrating customization files in the Unified Service Desk for Dynamics 365 to be a far smoother and more streamlined process.