Lessons Learned Upgrading to USD 4.1, IE Process to Chrome Process and Web Client to Unified Interface

Leave a comment

I recently went through an upgrade of Dynamics 365 and Unified Service Desk that consisted of the following:

  • Upgrading Dynamics 365 Web Client to Unified Interface
  • Upgrading Unified Service Desk 4.0 to 4.1
  • Changing Unified Service Desk Hosted Controls from IE Process to Chrome Process

There were several moving parts to the upgrade. In this post, I will talk through some of the tasks and challenges from a USD perspective.

First, the steps in the upgrade were something like below.

Upgrade Web Client to Unified Client Interface

I won’t go into too much detail in this post, but we did create a new App for our environment. In doing so, the URLs of our environment changed to include an appid=, which meant dealing with URLs in our configuration/code. We also took advantage of the new formContext client API where possible.

Upgrade USD 4.0 to USD 4.1

The simple part of this process involved running the USD server and client installation for USD 4.1 to upgrade the USD package. Once this is run, the USD solution will be upgraded to 4.1 and clients will be running the latest USD version.

Upgrade the USD 4.0 Custom Hosted Controls to USD 4.1

Any custom hosted controls need to be upgraded to point to the new USD assemblies. To do this, open your custom hosted control project in Visual Studio and point the references to the new version of Unified Service Desk. Depending on which version you are upgrading from, you may need to update the .NET version of the project.

At this point, Unified Service Desk is upgraded to 4.1.

Migrating from Web Client to Unified Interface Page and IE Process to Chrome Process

The next 2 steps are optional and were performed basically together, moving the USD Hosted Controls from non-Unified Interface Pages to Unified Interface Pages, and changing IE Process to Chrome Process.

Migration Assistant

There is a Web Client to Unified Interface Migration Assistant from Microsoft that migrates from web client pages to Unified Interface pages. The tool changes each of the applicable hosted control types (i.e. KM Control, Unified Interface Page, Unified Interface KM Control, CRM Page, Channel Integration Framework and Standard Web Application) to type Unified Interface Page. However, in our case, we performed this step manually. We did try using the migration assistant, but ran into some issues and also wanted to have more control over the process.

Unified Interface Page and Chrome Process

In migrating, we manually changed the hosted controls from the types mentioned above to Unified Interface pages, and at the same time, changed from IE Process to Chrome Process. We did this for all our controls at the same time.

PageReady and DataReady Events

In moving to the Unified Interface Page, the events BrowserDocumentComplete and PageLoadComplete are replaced with DataReady and PageReady. Any action calls under these events will need to be moved.

Web Resources

Next, the way the web resources are called has changed when using RunXrmCommand. Instead of embedding the code in the data of the hosted control, web resources are called in a particular format. Without doing so, code would not be executed properly.

Unified Interface Settings

Once the migration is complete, you can enable a Unified Interface Setting in the Unified Service Desk Administrator app to select your Unified Interface App.

Issues Found

Below are some issues that surfaced. Not all environments may encounter these, it largely depends on how your code is structured and your business requirements.

  1. Windows Navigation Rules. Some of our entities used multiple Dynamics 365 forms, where based on business logic a particular form is displayed. We found if a user selected a different forms using the form selector, or if we routed a user to a different form, windows routing rules would run (from the form’s entity to entity) that were not running in the previous version. We also had “catch all” rules in place to prevent users from clicking into records they didn’t need to navigate into. These were being affected by this change in routing rules. The result of these rules firing resulted in USD crashing. In reworking the rules, we were able to fix the problem.
  2. Non-USD bugs that surfaced in USD. One of the issues we found was the Quick Create form was not launching as expected when we opened it through JavaScript. The reason we saw it in USD was because we were hiding the navigation bar and toolbar in our pages, which surfaced a bug in the standard product. This was ultimately resolved in the latest version of Dynamics 365.
  3. Window.IsUSD. The way this worked is a little different in 4.1 and we found our code broken in places where this would return null. Moving this to parent.window.IsUSD appeared to resolve some issues, and per the documentation, “you must use it on the predefined events like pageReady and BrowserDocumentComplete”.
  4. Hiding Toolbars. Hosted Control toolbars that were hidden in 4.0 were now being displayed in 4.1.
  5. URLs. As we moved to a Unified Interface app, the URLs we had in our Navigate rules no longer worked as expected. Some of these did work (the system could figure it out), but as the format of the URL changed, it seems we had other issues when the URL was not properly formed. Also, some URLs were sending encoded text, which appeared to be a problem when opening the URL. Changing this to non-encoded URLs worked.
  6. Tabs and CTI. With the new Unified Interface displaying tabs separately, we found some code that was running on load of the page was no longer running, which especially came into play when CTI was automatically opening pages. We needed to create a hidden web resource on the first tab to account for this.

On a positive note, once the issues were resolved, the new system appears to be faster and stable. Note the challenges we faced may have been specific to our environment, and some may be resolved now with new releases of the platform.


Carl de Souza is a developer and architect focusing on Microsoft Dynamics 365, Power BI, Azure, and AI.

carldesouza.comLinkedIn Twitter | YouTube


Leave a Reply

Your email address will not be published. Required fields are marked *