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) {
    context.getAttribute("websiteurl").setValue(url);
    context.data.entity.save();
  }
}

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.

webResourceName=neil_Account_RunXrmCommands
functionName=UpdateWebsite
'[[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.

Leave a Reply

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

WordPress.com Logo

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

Google+ photo

You are commenting using your Google+ 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 )

w

Connecting to %s