USD – Unified Client Interface

With the release of version 3.3 of Unified Service Desk we now have support for the Unified Client Interface (UCI). I have started to experiment with this! In this post I will try to give you an overview of some of the key points I have found which you might want to be aware of.

Firstly I would like to point out that currently (at USD v3.3) ….. UCI for Unified Service Desk is a preview feature. What does this mean???? Well, Microsoft are simply saying that the feature is pretty new and likely to change. It is therefore possible you may find the odd issue. Additionally preview features could be enhanced or even potentially removed from future versions. Meaning their use is not recommended for production implementations. But generally you can use them for demonstrations and proof of concept work. I have known some companies to use preview features in production environments but doing so would be completely at your own risk.

I have no magic insight into Microsoft’s plans. But I’m reasonably confident that we’ll see a production version of the Unified Client Interface in a USD. As UCI is the intended new standard interface for all of Dynamics 365, hence why I would expect to see full support in USD in due course. (Disclaimer …. this is just my personal opinion and in no way a formal Microsoft policy!)

There has a Microsoft sample package for the Unified Client Interface that you might want to try. It will give you a good idea of what UCI might look like and also it might be useful to review how certain things work! Just run the packagedeployer and select the UCI sample application when installing USD.


The Unified Client Interface is dependent on Apps. Users must always first open an applicable UCI app. With previous versions of USD we had no concept of an app. Meaning the first new feature for me to describe is the addition of a app picker to Unified Service Desk.

The new App picker is not enabled by default. To enable it you’ll need to alter your UnifiedServiceDesk.exe XML Configuration file. This can be found in the programs directory of your Unified Service Desk client. Below you can see my programs files directory and the UnifiedServiceDesk.exe file within it.

You will need to edit this file, that can be done simply with notepad. (other editors are available!) Scroll down the file until you find the “” section. Then you’ll need to add the line of code shown in red below. This will enable the app selector.

    <add key="LoadSessions" value="false"/>
    <add key="enableJava" value="false"/>
    <add key="SupportUri" value=""/>
    <add key="emailSupportUri" value="N/A"/>
    <add key="MaxCrmConnectionTimeOutMinutes" value="20"/>   
    <add key="SelectAppModule" value="true"/>   

Now you have enabled the app selector, when you enter credentials into USD an additional screen will be displayed., Having picked your organisation you will be able to pick an app. Obviously if you are using UCI you’ll need to pick an appropriate Unified Interface app!

Once you load a USD configuration (that works with the Unified Client Interface) you’ll end up with an interface that looks something like the one shown below. Notice the tabs have been given a slightly different style and also that the look of agent scripts has been refreshed. The screen shot below is from my USD configuration but you’ll find that the Microsoft sample package has a similar look and feel.

Hosted Control Type

The introduction of the Unified Client Interface means we have a new hosted control type. Below you can see the hosted control I use for my account tab. Notice that the component type is “Unified Interface Page”. (When previously it would have been CRM Page.)

I have found that you can’t just alter the component type on an existing CRM Page hosted control! You’ll need to create a new hosted control for any tabs you’d like to display as the Unified Client Interface. I guess the reason being that a Unified Interface Page hosted control has a few different actions / events. (More on those in a second!)


Below you can see the events I have by default on a Unified Interface Page hosted control. These differ slightly to the events you might be familiar with from the CRM Page hosted controls.

I am still experimenting with Unified Interface Page hosted controls! (But I will document the differences I have observed so far below.)


Importantly we no longer have the commonly used BrowserDocumentComplete event! It has been replaced by PageReady.

PageReady behaves in the same way as BrowserDocumentComplete, in that it is triggered once the form has loaded.


Not forgetting that we also have a DataReady event, this event is triggered as soon as the replacement parameters are available when a form is loaded. We did have this event with the CRM Page hosted controls but had to be added manually. I believe it gets created by default with Unified Interface Page hosted controls.


I believe NavigationRequested is triggered each time we try to “pop” a record in a tab. I hesitated to use the word pop! As you might need to understand that the Unified Client Interface only generates In Place routes, no pop up occurs. (I will mention this again when reviewing window navigation rules!)

Uii Actions

By default the Unified Interface Page does not have the following actions, which would be present on CRM Page hosted controls;

  • DisableToolbarButton
  • EnableToolbarButton
  • LoadArea
  • lookupinfo
  • ReRoute
  • ToggleNavigation
  • ToggleRibbon
  • WaitForComplete
  • WaitForData

I haven’t yet tested to see if any of there uii actions can be added manually!

The following actions are added;

  • New – As far as I can tell so far, the New action seems to be the same as the New_CRM_Page action. (In that it loads new pages.)
  • Open – Open is the same as Open_CRM_Page, as it opens existing records.
  • SetVisualProperty – I’ve not used this on a Unified Interface Page, yet!


RunXrmCommand actions are different with the Unified Client Interface. I have already documented the differences in this post.

Essentially we can no longer use JavaScript that includes Xrm.Page with the Unified Client Interface. The new approach to RunXrmCommands allows us to specify a webresource and function to run. This approach allows the context to be passed into your JavaScript function. (Therefore removing the need for Xrm.Page commands!)

Window Navigation Rules

Window navigation rules are slightly different with the Unified Client Interface! With the standard web client in CRM Page hosted controls we often have a pop up route. (Popups commonly occur when opening a new record, meaning I often have a window navigation rule which creates a new session when a popup occurs from a search tab etc.)

With UCI we get no popup routes, all routes are “In Place” routes. The implication of this is that you might need to review your approach to window navigation rules. I actually think this could be a benefit as with CRM Page hosted controls we typically created two navigation rules, one for the Popup route and another for the In Place route. Having just one route therefore means we can have less navigation rules.

Enhanced look and feel

Whilst converting my configuration to work with the Unified Client Interface I found it really useful to review how various actions / hosted controls are defined in Microsoft’s sample package. This was very true when understanding the approach needed to implement the enhanced screen layout show in my screen shot at the start of this post.

Assuming you might also want to clone this style, I will provide a few tips below…..

Firstly, the panel layout isn’t the standard one. Notice that the Panel type is XAML. I won’t include a copy of the XAML here. As all I did was copy and paste if from the Microsoft sample package.

Next you will find three actions that need to exist on the DeskTopReady event of your Global Manager. These are;

  • Set UCI Custom Theme Normal Contrast
  • Set UCI Custom Theme Tabs
  • Set UCI Custom Theme Toolbars

I won’t list the details for each of these actions here! Simply as your quickest approach will be to load the sample package and cut and paste the details for each action from there! Each action is a SetTheme action that includes some XAML code to correctly format the tabs / toolbars etc. (Depending on your requirements you may find you need to edit this XAML!!)

Hopefully this post has includes a few useful tips around the new Unified Interface Client support. I am really enoying working with the new interface and I’m looking forward to when I can implement it in a production environment.

5 thoughts on “USD – Unified Client Interface

  1. Hello Neil, we have tried to install the-usd-accelerator_2_0_0_1 with Package manager as you recommended it, but we have an error, a depency is missing, After reading the error we think that the solution MicrosoftDynamicsScheduling ( is missing, ok it isn’t installed on my environment but I don’t find where I can downloaded this solution.
    Have you got any ideas where I can download the solution ? Or how I can fix it?

    PackageDeployment Information 8 11/12/2018 15:50:20 Fetching Data for Neil’s USD Accelerator
    Microsoft.Xrm.Tooling.Connector.CrmServiceClient Verbose 16 11/12/2018 15:50:20 Executed Command – Retrieve : Trying to Read a Record. Entity = importjob , ID = c1b10cbe-0c90-4477-aebd-e85a9c141d4b : RequestID=d9dd143e-950a-45c2-927d-d9e2d652503c : duration: 00:00:00.1413749
    PackageDeployment Information 8 11/12/2018 15:50:20 Import for Neil’s USD Accelerator, Progress is : 15.3846153846154
    PackageDeployment Information 8 11/12/2018 15:50:20 Solution Import Result = failure
    PackageDeployment Information 8 11/12/2018 15:50:20 Neil’s USD Accelerator Import Failed
    code: 0x8004801D
    Description: Solution manifest import: FAILURE: The following solution cannot be imported: NeilsUSDSolution. Some dependencies are missing. The missing dependencies are : , ProductUpdatesOnly : False
    Details NeilsUSDSolution<MissingDependencies><MissingDependency><Required key=”22″ type=”61″ schemaName=”msdyn_/fps/ScheduleBoard/ScheduleBoard.html” displayName=”msdyn_/fps/ScheduleBoard/ScheduleBoard.html” solution=”MicrosoftDynamicsScheduling (” /><Dependent key=”2″ type=”62″ schemaName=”neil_TheUSDAccelerator” /></MissingDependency></MissingDependencies>False


    • Hi Aurelien,

      I think I understand this error and I am working on a proper solution!

      It is happening because I have included the Field Service Scheduleboard into the UCI app that makes up my USD Accelerator solution. I have done this as I want to support Field Service.

      But making it part of the solution means you might see this error if Field Service isn’t installed. Whenever I use The USD Accelerator I tend to create a trial and select the “all of these” option. Meaning Field Service entities will be present even if I am not using them.

      So short term you’ll need to install into an environment that includes Field Service.

      I am working on a new version of The USD Accelerator that will resolve this.




  2. Hi Neil,

    Thanks for the useful blog. We are currently migrating to the new UI and have a lots of window navigation rules to popup pages in a separate tab and this seems to work as expected in classic UI. Now with new UI it seems to be broken and only appears to perform like “In Place”.

    You have mentioned in the blog that “With UCI we get no popup routes, all routes are “In Place” routes”. Does it mean I can no longer make my pages to open in a separate tab and it is always going to overwrite the existing page? If that is the case, then user might lose the information that they entered in the previous page.

    Kindly clarify.


    Liked by 1 person

    • Hi

      With new UI routes are typically in place but we can still use a window navigation rule to trigger a route window action. Meaning the tab can still be loaded in a separate tab.

      Hope this helps



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s