Create a user-defined event

Unified Service Desk provides you with predefined events for hosted controls based on the type of the hosted control. Apart from these predefined events, you can also create your own events in Unified Service Desk, which are called user-defined events. You can use the FireEvent action or the event moniker to run user-defined events.

Use the FireEvent action

All of the predefined and custom Unified Service Desk hosted control types, except for the CCA Hosted Application have a special UII action called FireEvent. You can call this action to initiate a user-defined event from that control. This is a convenient way to group multiple action calls into a single call, effectively creating a function within Unified Service Desk. It is also a reasonable way to test events and their action sequences before deployment.

The first parameter to the FireEvent is the name of the event:

name=MyEvent  

All subsequent name/value pairs become the parameters to the event and thus can be used as replacement parameters within the actions that are called as a result. For example, if you pass the following parameter list:

name=MyEvent  
var1=[[account.name]]  

This will fire the custom event MyEvent event enabling the ability to create an action call that uses the var1 parameter as follows:

Hosted Control=Some Hosted Control  
UII Action=Some action on the Hosted Control  
Data=[[var1]]  

This passes the event parameter as a data parameter to the hosted control action. In this example, that means the data parameter to the hosted control will be the account.name value from the session.

Use the event moniker

You can create a custom event on a hosted control, and then call it using the following event moniker syntax:

http://event/?EventName=<EVENT_NAME>&key=value&key=value&…  

In the syntax, you specify the key=value pair to pass parameter list to be used when the event is triggered.

Consider an example where you want to raise a user-defined event whenever the title of the case on the case form changes in the Common Data Service platform. To do this:

  1. Create a new event, called TitleChanged, for the Incident hosted control in the Common Data Service platform.

  2. Create an action call, called Action Call for Title Change, with the following values:

    Field Value
    Name Action Call for Title Change
    Hosted Control Incident
    Action RunXrmCommand
    Data function titleChangeReaction() {
    window.open("http://event/?EventName=TitleChanged&NewTitle="+encodeURIComponent(Xrm.Page.getAttribute("title").getValue()));
    }
    Xrm.Page.getAttribute("title").addOnChange(titleChangeReaction);
  3. Add the new action call that you created to the BrowserDocumentComplete event of the Incident hosted control. More information: Add action calls to an event

    When the TitleChanged event is triggered, the following request is raised: http://event/?EventName=TitleChanged&NewTitle=<NEW_TITLE>

    This will cause the TitleChanged event to be triggered with the following data parameter: NewTitle=<NEW_TITLE>

    If you use JavaScript in the Common Data Service platform to invoke an event in Unified Service Desk using the event moniker (http://event/?EventName=<EVENT_NAME>&key=value&key=value&…), you can use the window.IsUSD property to determine whether the JavaScript code is running under Unified Service Desk when the event is invoked. The following code sample can be included in your JavaScript code to ensure that the event is invoked only when the calling JavaScript is running within Unified Service Desk.

if ((window.IsUSD != null) && (window.IsUSD == true))  
{  
   window.open(http://event/?EventName=<EVENT_NAME>&key=value&key=value&…);  
}  

See also

Events
Hosted control types and action/event reference
Manage hosted controls, actions, and events
MSDN: Use JavaScript with Microsoft Dynamics CRM