USD – UCI and RunXrmCommand

Version 3.3 of Unified Service Desk (USD) has introduced a new hosted control component type of “Unified Interface Page“, which supports the new Unified Client Interface (UCI). These have several differences to the “CRM Page” hosted controls we have traditionally used with the standard web client. In this post I will explore just one of these differences, RunXrmCommands.

I’ll begin by reminding us of the existing concept of a RunXrmCommand. Below you can see a simple example of a RunXrmCommand that would work with a “CRM Page” hosted control. The command simply runs some JavaScript directly on the form. In my example below the code sets the accounts website field to a replacement parameter and then saves the account. Pretty simple stuff.

However, this approach will no longer work with the “Unified Interface Page” hosted controls. I hope you know “Xrm.Page” does not work with the UCI. (And that Xrm.Page has been deprecated so will be removed from Dynamics 365 at some point.)

Instead of using Xrm.Page our code must be aware of the context within which it is running. The problem is that with the old approach to RunXrmCommands we don’t have a method of passing the context.

Additionally notice that my code used replacement parameters directly in the function. I’ll come back to this in a second, as we also have a new approach to handling replacement parameters.

As an example, let’s look at how I need to change this action to work with the Unified Client Interface.

Step One – Create a Web resource.

The first thing we do is create a web resource in the customizations area of Dynamics 365.

My web resource was simply a small piece of JavaScript, I have shown it below.

My code is shown below. The important things to note are the parameters on the function. The first is “context”, and the second will contain the contents of a replacement parameter. I’ll show you how to pass that into this function in second!

Unified Service Desk will only substitute my replacement parameters directly in the actions being run. Meaning I can no longer directly use replacement parameter in my JavaScript but I can pass them in as parameters.

Also notice that instead of using “Xrm.Page” I have used “context”.

function UpdateWebsite(context, param1) {
  var url = param1;
  if (url !="" && url != null) {

Step Two – Change my Action

If your hosted control is of type “Unified Interface Page” then RunXrmCommands can be used to call a function held in a web resource.

You can see below how my action changes when using the Unified Interface.

'[[Account Website.url]+]'

Notice the data field, it no longer contains the actual JavaScript I am going to run. Instead it has three lines.

The first line defines the name of the web resource. “webResourceName=xyz”

The second line gives the function name. “functionName=xyz”

The third line is optional. This is the replacement parameter I want to pass into my function.

Tip: If you have more parameters you’d like to pass simply list them, one on each line.

I hope you can see that this new approach is quite simple to adopt. I guess it may seem long winded if you only have a single line of code to execute! But I actually think it will lead to a more structured coding approach. I have found that currently this style of RunXrmCommand only works with the “Unified Interface Page” hosted controls.

2 thoughts on “USD – UCI and RunXrmCommand

  1. Hello Neli,
    My question is related to CRM Page hosted controls instead:
    How can I code Action Call scripts using V9 API Client?
    Web resources (webResourceName) works fine in “Unified Interface Page” but not in “CRM Page”
    I do not want to use command as it is deprecated already.
    Any Idea?

    Thanks Neil.


    • Hi

      Sorry but with CRM Page, you need to use
      Xrm.Page as the older version of RunXrmCommand that work with CRM page aren’t aware of the context. Obviously XRM.Page is only deprecated and still works perfectly well.

      Having said that you should start to move away from it ready for the day it goes and that move should ideally also include a migration away from the classic web client to the Unified Interface. We should expect that in the fullness of time the classic web client will also be deprecated, obviously that won’t happen until feature parity has been reached. But I’d encourage everyone to move to Unified Interface and also remove any XRM.Page code.

      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