Inserting USD events into HTML javascript logic and acting upon it

One of the key benefits of having Unified Service Desk host web applications rather than just displaying them in an iframe within the web client is its inherent ability to perform bidirectional communication with the web application without modifying its source code.  This is particularly important when you don't have control over the development of the application either because it is built by a 3rd party or another department.  Even if you do have control, you'd have to figure out how to code your application differently depending on whether it is hosted within USD or not, which is not ideal. With an iframe, security limits you to pushing URL's, which is a very limited form of communication, unless the host and hosted applications can agree on a protocol such as the HTML 5 messaging protocol.  These are fine methods when you have the ability to define both applications, but not so good when you need to communicate with an application that cannot or will not be so cooperative.

Unified Service Desk, because it hosts the browser itself, has much more control than a simple iframe.  It can inject javascript to set values, modify functions, or cause HTML events such as button clicks.  But another important capability of Unified Service Desk is its ability to effectively tell an application (whether it really knows it or not) to notify it about events as well.  This can be quite useful for things such as intercepting click events and have them run action calls that might, say, automatically load a map with directions in another tab when an address was
saved on a web form.  You might also detect when data is changing in fields and fire an event up to USD to tell it about the new data and populate data parameters to share with other hosted controls.

To do this is relatively straight forward in concept but with intimate knowledge of how javascript works, can become quite powerful.

Our Example

Now let's suppose we have the following javascript function in a 3rd party web page that is hosted within USD.  You can load your browser's debugger to see the javascript code on the page.  It happens to be called when the user clicks a button in the page.

 function MyButtonWasClicked()
 {
 // the web application does something here.
 }

In my case, I still want the code inside MyButtonWasClicked() to run but I want USD to know when this function was called as well.  What we want to do is insert USD into the logic on the page without disrupting it's functionality.  To achieve this, we want to start by adding an action to the page's BrowserDocumentComplete or PageLoadComplete event in USD, whichever is appropriate.

HostedControl:
<My Hosted Control>

Action:
RunScript

Data:
var MyButtonWasClickedOld = MyButtonWasClicked; //save the old method
MyButtonWasClicked = function() // create a new version of the function
{
   window.open("https://event/?eventname=buttonclickevent&param1=value1"); // fire the event to USD
   MyButtonWasClickedOld(); // call our old method
}

 

This action will replace the current implementation of the MyButtonWasClicked() function within the page and only when USD loads it. Outside USD, it will continue to work as it always has.  When the user clicks the button, it will call the new version of the function and in this case will call window.open with a special syntax that I describe soon, followed by calling the old implementation of the function.  In this case, we are notifying USD of the event before running the old implementation.  You could easily reverse that behavior or even eliminate the old behavior if it was desired.

Window.open event syntax

When a page is requested that starts with the special syntax of https://event/?, USD interprets it as an event.  This special URL must always have a parameter called eventname.  This parameter indicates the name that will be used in the USD event configuration. 

Now in CRM, lets add an event to our hosted control to do something with this event.  Go to the Unified Service Desk events configuration link.

 

 

Click New to add a new event.

 

 

In the event's name, enter the name exactly the same as specified in the eventname parameter of the event URL.

 

 

The Hosted Application field should be populated with the hosted control that contains your web application that you injected the script and that will produce the event.  You can then save this and add Action Calls to this event as you see fit.  In this case, let's just plan to display the event parameter, param1, in a dialog box.  Click Add to create a new action call within your new event.

 

Hosted Control:
CRM Global Manager

Action:
DisplayMessage

Data:
text=My parameter is [[param1]]

 

Wrapping up

Now when you run Unified Service Desk and click the button within the web application, your event will be fired.  You will see the event line in the USD Debugger as well so it's a good way to make sure your event is properly firing.  Also, since your event is mapped to a configured USD event, your action call will run as well.  The parameters you supplied in your event URL are all passed to the action calls linked to the event you created so you can use them when creating your action calls. 

If you need to transfer a larger amount of information from the application to USD, passing it in the event is not going to work because of the limitations on the length of URL's.  A better approach would be to fire the event without the large data set, and call RunScript, have it assemble the data in javascript and return it from the RunScript call.

Hosted Control:
<My Hosted Control>

Action:
RunScript

Data:
function RetrieveLargeData()
{
  return largeDataVariable;
}
RetrieveLargeData();

 

When you add this action call to your event, it will obtain the largeDataVariable and return it to the $Return entry in the Data Parameter list.  This method can handle quite a large amount
of data.

Comments

• Anonymous
  November 23, 2015
  Are there any plans to use Edge browser inside USD, simple reason to ask this is that very soon IE will become obsolete and unsupported and Edge browser doesn't support any of the previous COM based technologies (BHO, ActiveX etc..) blogs.windows.com/.../a-break-from-the-past-part-2-saying-goodbye-to-activex-vbscript-attachevent once this happens , USD's USP will become dated.

• Anonymous
  November 23, 2015
  Edge isn't quite capable yet.  Our teams are communicating with the Edge team.

• Anonymous
  November 24, 2015
  Currently Edge does not provide enough hooks for USD to provide the same level of integration that we can do with IE. We are working with the Edge team in exploring options in integrating USD with Edge. We do not have anything to share at this point.

• Anonymous
  November 24, 2015
  Can you clarify something for me? I'm looking at using USD to integrate a "Used Car Stock Search" web application with Dynamics. The web application already exists for Stock Items, and is used elsewhere. We don't want to change the code of that application. Dynamics receives inbound leads for expressions of interest from various channels. The data in the leads is in very generic terms (e.g. "I want a Ford Mondeo, <10,000 miles, what have you got?"). What I want to do is present a call handler with the incoming lead from Dynamics, and the Used Car Stock web application. I want the call handler to be able to search and find stock for the customer and then make an outbound call to discuss. If the customer is interested in any of the stock items found I want to capture the Stock Item ID from the web app and save it into the CRM opportunity record. This is so that when the customer calls back we can quickly see the stock items they previously showed interested in, and of course show the current availability (in the external app). Am I right in saying that I could capture the StockID numbers selected in external web app and save them into a field in the opportunity record using the technique above?

• Anonymous
  November 25, 2015
  Paul, that is a typical use case. I would suggest reaching out to a local Partner to help you configure that. This blog post describes some similar techniques but are for events originating from a custom web page rather than just pulling data from a page, which is similar but not as complicated.

• Anonymous
  November 26, 2015
  Hi Jayme, First of all i would like to let you know that i attended training on USD, conducted by you in Microsoft Mumbai. Could you please resolve one of my USD query ? I am working on USD from last 6-7 months and i am facing one major challenge while working with WNR. i am not able to pass dynamic parameter in URL field of WNR. For example, I have "Send SMS" button on Contact entity and i want it to be open in separate USD tab as soon as user click on button. But problem what i am facing is url that call on click of Send SMS button takes some parameter from contact entity like mobile number etc. Now when i was trying to create WNR so that as soon as user click on sendsms button it gets open in new tab let say "Send SMS" but i am not able to perform the same. I would like to clarify whether WNR takes hardcoded value in URL field or we can pass some dynamic parameter from USD context. If yes then pls let me know how can be achieve this. Same i also have some HTML button on contact form to open Associated view of contact. And i am not able to redirect it through WNR because the limitation i found in WNR is either it can redirect to a particular entity record or redirect to any hardcoded url. Please help me out on this...

  • Anonymous
    May 10, 2016
    In the WNR, the URL field is a substring match. You only need to specify the unique part of the URL to match. If you want to insert stuff into your URL before using it, you need to do a little extra work. In your WNR, specify action as None. Then in the navbar menu, select Action Calls. Add an action call there that calls Navigate or whatever appropriate action call you want to have in response to your button click. The original URL is available as a [[SUBJECTURL]] replacement parameter in any attached action calls. You could use scriptlets in there to manipulate this URL and supply to whatever action you need to call, such as Navigate.

• Anonymous
  December 03, 2015
  how can i open external webpage in a new application tab or session tab in Unified Service Desk.

  • Anonymous
    May 10, 2016
    You can use Window Navigation Rules to direct popups to a tab, or you can call Navigate on a hosted control to direct to a specific URL of your choice.

• Anonymous
  March 28, 2016
  Thank you for this, exactly what I was looking for.

• Anonymous
  April 20, 2016
  Excellent infoThanks