Global Manager (Hosted Control)

Article
02/21/2017

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2013, Dynamics CRM 2015, Dynamics CRM 2016

The Global Manager hosted control type is the core of Unified Service Desk, and an instance of this hosted control is required by Unified Service Desk. This hosted control loads and reads all the Unified Service Desk configuration data from Microsoft Dynamics 365 at application startup, interprets the window navigation rules, provides data to the toolbar components and agent scripts, and manages the data for the session. Only a single instance of the Global Manager hosted control type can be loaded.

Important

The three sample application packages for Unified Service Desk, New Environment, CRM Web Client, and Interactive Service Hub, come preconfigured with an instance each of the Global Manager hosted control type. For information about the sample applications, see TechNet: Deploy sample Unified Service Desk applications to CRM server using Package Deployer.

In addition to providing interpretation for most of the functions in Unified Service Desk, the Global Manager hosted control type also provides the multi-language features in the system so that you can localize UI strings and messages in your application in multiple languages. For more information, see Add multilanguage support for your agent applications. It also provides the search provider, which is designed to be generic and adaptable through configuration.

In This Topic

Create a Global Manager hosted control

Predefined UII actions

Predefined events

Create a Global Manager hosted control

While creating a new hosted control, the fields in the New Hosted Control screen vary based on the type of hosted control you want to create. This section provides information about the specific fields that are unique to the Global Manager hosted control type. For detailed information about creating a hosted control, see Create or edit a hosted control.

Global Manager hosted control

In the New Hosted Control screen, under the Unified Service Desk area, select Global Manager from the USD Component Type drop-down list. Also, ensure that you set the Sort Order value of this hosted control to 2 to ensure it is loaded by your agent application immediately after the connection has been established to Dynamics 365 using the Connection Manager hosted control. For information about other General fields, see Create or edit a hosted control.

After you save the record, the Language Services area becomes available where you add resources for adding localized strings for your agent application’s UI. For information about how to add language resources, see Add multilanguage support for your agent applications.

Predefined UII actions

Global Manager provides a series of predefined actions that allow you to manipulate Dynamics 365 record data through the web services. These can be used during configuration to perform advanced functions in Dynamics 365.

The following predefined UII actions are available for the Global Manager hosted control type:

Audit

Add an audit entry to the Unified Service Desk audit logs. For more information, see Technet: Configure auditing in Unified Service Desk

Parameter	Description
Name	The audit entry name. You must add an option under the Options area (Settings > Unified Service Desk > Options (How do I get there?)) with the value set to 1.
Action	String representing the action that is being audited.
TargetApplication	String representing the target application for the audit.
CustomerId	String representing the customer ID.
ContextId	String representing the context ID.
ApplicationId	GUID of the hosted control for the auditing.
AgentState	String representing the agent state
ActionData	This is the data to write out to the audit entry. If this parameter isn’t explicitly provided, it will use all the remainder lines in the Data field of the action call definition.

CallDoAction

Calls an action on another hosted control.

Parameter	Description
panel	This is the panel to find the active application, if no application is specified.
action	This is the action to call on the hosted control.
data	This is the data parameter to pass to the action.
application	This is the hosted control name for which you want to execute an action call. If this is specified, the panel parameter is ignored.

ClearAppBar

Undocks the specified hosted control in the client application.

Parameter	Description
ApplicationName	Name of the hosted control to undocked. If this parameter is not supplied, the client application main window is undocked.

ClearEntityList

Clears the list of accumulated search results, and should always be called before calling the DoSearch action

Parameter	Description
global	True if you want the search results tied to the global session to be cleared. You must be careful while storing search results in the global session as these are not automatically cleared by the system. In this case, you must call the ClearEntityList action before calling the DoSearch action.

Close

Closes the hosted control. Unlike the CloseActive action, if this tab is displaying more than one page, it will close all the pages displayed in the tab in your agent application.

CloseActive

Closes the active hosted control on the specified panel.

Parameter	Description
	The first line in the action call should contain the name of the panel to locate the active application. If no parameter is specified, MainPanel is assumed.

CopyToClipboard

Copies or appends the article URL to Clipboard.

Parameter	Description
data	Data that you want to be copied. You can also use replacement parameters. For example: data=[[$context.title]]
append	Indicates whether or not to append the data to the Clipboard. Set true or false. For example: append=false.

CopyToContext

Copies a value or series of values to context variables. Context variables can be serialized with the session. This action takes a series of name=value pairs. The name is the name of the context variable.

CopyLogicalEntityToContext

Copies values from an entire section of the data parameters to the context.

Parameter	Description
LogicalName	The type or section of data parameters to copy values from.

CloseActivity

Closes an activity record in Dynamics 365.

Parameter	Description
Id	The GUID of the activity record to close.
LogicalName	The logical name of the activity to close.
StatusCode	The display name of the final status code after the activity is closed.
StateCode	The display name of the final state code after the activity is closed.

For example, to close a phone call activity, you must specify the following:

Id=<GUID of the phone activity record>

LogicalName=phonecall

statuscode=Received

statecode=Completed

After the activity record is closed, the $Return system replacement parameter will be populated with a Boolean value indicating whether the action was successful.

CreateEntity

Creates a new record in Dynamics 365.

Parameter	Description
LogicalName	The logical name of the entity to create

Each subsequent line in the parameter list contains a series of Name=Value pairs that will define your other fields to populate on create.

Entity References can be described like the following:

Param=EntityReference(“logicalname”, “id”)

OptionSetValues can be specified like the following:

Param=OptionSetValue(value)

Booleans can be described like the following:

Param=Boolean(value)

PartyList (used with email) can be described like the following:

Param=PartyList(email[“test@test.com”], er[“contact”, guid])

You can use any number of email and er entries to represent email addresses and entity references respectively.

Other values such as string values can be specified like the following:

Param=value

Once the record is created, the $Return value will be populated with the GUID of the newly created record.

CreateSession

Creates a session.

DeleteEntity

Deletes a record in Dynamics 365.

Parameter	Description
Id	The ID of the value to delete. This must be the GUID of the record to delete.
LogicalName	The logical name of the entity to delete.

DoRoute

Can be used to test your window navigation rules by simulating a popup window from a specific hosted control. It may be used in production to trigger the window navigation rules manually as per the requirement.

Parameter	Description
name	The ID of the entity that is the target of the queueItem
entity	The Logical Name of the entity that is opened in a pop-up window.
id	The ID of the entity that will be opened in a pop-up window.
frame	The frame from which the popup is said to occur.

DoSearch

Calls the Dynamics 365 web services using the FetchXML defined as an entity search in Unified Service Desk For more information about defining an entity search, see Search data using entity searches in Unified Service Desk.

Parameter	Description
name	The name of the entity search to be used for searching the record.
global	True if you want the search results tied to the global session to be cleared. You must be careful while storing search results in the global session as these are not automatically cleared by the system. In this case, you must call the ClearEntityList action before calling this action.
maxcount	The maximum number of records to store in the EntityList results from this call.

Note

By default, the page count (number of records per page) for a result set is set to 50. This implies that if there are more than 50 records returned, it will be displayed in pages. If you want to specify a different page count value for the DoSearch action, specify the new value in the EntitySearchPageCount option. More information: TechNet: Manage Options for Unified Service Desk

When you call the DoSearch action, the $Return replacement parameter displays the number of records found and stored in EntityList as a result of this search. More information: $Return.

DisplayMessage

Displays a message box to the user.

Parameter	Description
text	This is the text displayed in the message box. If this parameter is not specified, any remaining text (remainder parameter) or empty string will be used.
caption	This is the caption displayed in the message box. If no caption is specified, Dynamics 365 Message will be used.

ExecuteOnDataAvailable

Delays the execution of the sub-actions until a specified set of replacement parameters becomes available. A time-out value may be specified to limit the amount of time to wait for the replacement parameters to become available. If no time-out is specified, it will wait indefinitely or until the session ends. More information: Blog: How to use the special actions, ExecuteOnTimeout, ExecuteOnDataAvailable, ExecuteOnExpressionTrue

Parameter	Description
milliseconds	The time, in milliseconds, to indicate the amount of time to wait before this action expires, and is canceled. The remaining parameters should contain replacement parameters that need to exist before sub-actions can execute. Data Parameter Example: milliseconds=5000 [[account.Id]] [[incident.Id]]

milliseconds

The time, in milliseconds, to indicate the amount of time to wait before this action expires, and is canceled. The remaining parameters should contain replacement parameters that need to exist before sub-actions can execute.

Data Parameter Example:

milliseconds=5000
[[account.Id]]
[[incident.Id]]

Important

This action applies to all the hosted control types. This action isn’t exposed by default when you create an instance of a hosted control type. To use the ExecuteOnDataAvailable action with an instance of a hosted control type, you must explicitly add a UII action called ExecuteOnDataAvailable to the respective hosted control instance. More information: Add a UII action to a hosted control

ExecuteOnTimeout

Delays the execution of the sub-actions until a specified time elapses. A time-out value is required to indicate when the sub-actions should be run. More information:** **Blog: How to use the special actions, ExecuteOnTimeout, ExecuteOnDataAvailable, ExecuteOnExpressionTrue

Parameter	Description
milliseconds	The time, in milliseconds, to indicate the amount of time to wait before the sub-actions execute. Data Parameter Example: milliseconds=5000

milliseconds

The time, in milliseconds, to indicate the amount of time to wait before the sub-actions execute.

Data Parameter Example:

milliseconds=5000

Important

This action applies to all the hosted control types. This action isn’t exposed by default when you create an instance of a hosted control type. To use the ExecuteOnTimeout action with an instance of a hosted control type, you must explicitly add a UII action called ExecuteOnTimeout to the respective hosted control instance. More information: Add a UII action to a hosted control

ExecuteOnExpressionTrue

Delays the execution of the sub-actions until a specified JavaScript expression returns true. A time-out value may be specified to limit the amount of time to wait before expiring. If no time-out is specified, it will wait indefinitely or until the session ends. More information: Blog: How to use the special actions, ExecuteOnTimeout, ExecuteOnDataAvailable, ExecuteOnExpressionTrue

Parameter	Description
milliseconds	The time, in milliseconds, to indicate the amount of time to wait before this action expires and is canceled. The remaining parameter is a JavaScript expression to evaluate. When this expression is true, sub-actions will execute. Data Parameter Example: milliseconds=5000 function IsAccountLoaded() { return “[[account.Id]$+]” != “”; } IsAccountLoaded();

milliseconds

The time, in milliseconds, to indicate the amount of time to wait before this action expires and is canceled. The remaining parameter is a JavaScript expression to evaluate. When this expression is true, sub-actions will execute.

Data Parameter Example:

milliseconds=5000
function IsAccountLoaded()
{
return “[[account.Id]$+]” != “”;
}
IsAccountLoaded();

Important

This action applies to all the hosted control types. This action isn’t exposed by default when you create an instance of a hosted control type. To use the ExecuteOnExpressionTrue action with an instance of a hosted control type, you must explicitly add a UII action called ExecuteOnExpressionTrue to the respective hosted control instance. More information: Add a UII action to a hosted control

ExecuteScriptlet

Executes the specified scriptlet.

Parameter	Description
	Specify the name of the scriptlet to execute in the Data field.

FireEvent

Fires a user-defined event from this hosted control.

Parameter	Description
name	Name of the user-defined event.

All subsequent name=value pairs become the parameters to the event. For more information about creating a user-defined event, see Create a user-defined event.

GetTemplate

Retrieves the contents of a merged email template.

Parameter	Description
name	Name of the template to retrieve.
id	The ID of the entity to associate with this template for the merge operation.

InvokeCTI

Simulates CTI events

Parameter	Description
type	This is the type of CTI event, such as phone call or chat.
appname	The desktop manager name to be used for this pop-up simulation.
ani	The automatic number identification (ANI) or callers phone number.
dnis	The DNIS or dialed number.
	All remaining parameters will be passed as parameters to the CTI event processor.

LaunchURL

Launches a URL in Internet Explorer outside of the Unified Service Desk application. You must specify the URL as a parameter in the Data field.

LookupQueueItem

Looks up a queueitem in the system and obtain the information.

Parameter	Description
Id	The ID of the entity that is the target of the queueItem
EntityType	The type or logical name of the entity referred to in the Id field.

The resulting queueitem details will be placed into the queueitem replacement parameter and may be referenced later.

MoveApplicationToPanel

Moves a hosted control to the specified panel in the client application.

Parameter	Description
app	Name of the hosted control to move.
panel	Name of the target panel.

MoveToPanel

Moves hosted controls between panels at runtime.

Parameter	Description
app	Name of the hosted control to be moved.
panel	Target panel for the hosted control.

New_CRM_Page

Creates a page for creating a new Dynamics 365 record of the entity specified, and treats the page as a popup from the specified hosted control. The window navigation rules are evaluated to determine the location where the page to create the entity record is displayed.

Parameter	Description
LogicalName	The logical name of the entity for creating a new instance.

Note

The rest of the parameters should consist of name=value pairs. These are the additional pre-populated values in the form for creating a new record for the specified entity. For more information about using this action, see step 4 in Walkthrough 7: Configure agent scripting in your agent application.

Open_CRM_Page

Opens an existing instance of the entity specified and identified by the ID, and treats the page as a popup from the specified hosted control. The window navigation rules are evaluated to determine the location where the popup should be displayed.

Parameter	Description
LogicalName	The logical name of the entity to open.
id	The ID of the entity record to open.

Pause

Pauses execution of the action without blocking message processing. This action is different from suspending the current thread for the specified amount of time (Thread.Sleep) because the action allows the processing to continue. This action is useful when you are waiting for web operations to complete.

Parameter	Description
milliseconds	The number of milliseconds to pause.

Pops up a URL from the hosted control and runs the window navigation rules against it for routing the popup to the appropriate location.

Parameter	Description
url	Routes a popup from this hosted control using this URL as if it were a popup requested from the displayed control.
frame	The frame from which this popup originated.

RealignWindow

Displays the hosted control at the specified location on a monitor. You can display hosted control on up to two monitors. This action is applicable for hosted control instances that are configured to be placed on a USDFloatingPanel or USDFloatingToolPanel panel type.

Parameter	Description
screen	Specifies the screen on which to display the hosted control. Valid values are 1 or 2. If you don’t specify this parameter, 1 is passed by default.
left	Specifies the position, in percentage, from the left of the screen on the target monitor where the hosted control should be displayed. Valid values are 0 through 100. If you don’t specify this parameter, 0 is passed by default.
top	Specifies the position, in percentage, from the top of the screen on the target monitor where the hosted control should be displayed. Valid values are 0 through 100. If you don’t specify this parameter, 0 is passed by default.
width	Specifies the width, in percentage, of the hosted control window on the target monitor. Valid values are 1 through 100. If you don’t specify this parameter, 100 is passed by default.
height	Specifies the height, in percentage, of the hosted control window on the target monitor. Valid values are 1 through 100. If you don’t specify this parameter, 100 is passed by default.

ReadSettings

Reads the previously saved settings from the $Settings replacement parameter.

Parameter	Description
readfromcache	True if you want to read the local cached version of these settings. False or missing otherwise.

RedoScreenPop

Pops the last screen again. This can be useful in cases where the session limit was reached and the pop up wasn’t successful, or you closed the session but more work is required. This action requires no parameters.

ResetLocalCache

Resets the configuration cache in Unified Service Desk. The next time Unified Service Desk is started, it will download the configuration from the server. The user must have write access to the msdyusd_usersettings entity for this action to work.

RouteToQueue

Routes an entity to a queue in Dynamics 365.

Parameter	Description
destination	The target queue ID. This is mutually exclusive with the destinationqueuename parameter
destinationqueuename	This is the name of the queue to route the entity.
entitytype	This is the logical name of the entity to be routed
entityid	This is the GUID/Id of the entity to be placed into queue.

SaveAll

Saves all forms in hosted control that allows multiple pages to be displayed (Allow Multiple Pages = Yes). If the hosted control allows only a single page to be displayed (Allow Multiple Pages = No), this is equivalent to the Save action.

SaveSetting

Stores a user specific setting.

Parameter	Description
name	The name of the setting. This will show up in the$Settings replacement parameter.
value	The value of the setting to save.

SetTheme

Applies a theme to modify the layout or look and feel of components of the user interface. More information: Customize the appearance of your application

Parameter	Description
clear	True if you want to completely clear the current theme before applying the specified theme. If this parameter is false, or not specified, the new theme information will be merged with the current theme.
	The remainder parameter (what is left after the other parameters are removed), should contain the name of the theme to use. This should be a XAML file (renamed to XML and uploaded as a web resource) web resource name, a URL from an anonymous access server, or the raw XAML representing the theme.

SetAppBar

Docks a hosted control to the specified edge of the client application main window.

Parameter	Description
ApplicationName	The name of the hosted control to dock. If this parameter is specified, the parent window hosting this hosted control will be docked.
width	The width in pixels of the docked window. If this is not specified, the current width of the window is used.
height	The height in pixels of the docked window. If this is not specified, the current height of the window is used.
Edge	The edge to dock against. If nothing is specified, Top is assumed. Specify one of the following values: Top, Bottom, Left, or Right.

SetEventTimer

Sets an event timer to start.

Parameter	Description
name	Name of the event timer.

SetSize

Sets the width and height of the hosted control. This is particularly useful when using "auto" in your panel layouts.

Parameter	Description
width	The width of the hosted control.
height	The height of the hosted control.

SetWindowProperty

Sets the window state for the client application main window.

Parameter	Description
WindowState	One of the following values: maximized, minimized, or normal.

ShellExecute

This action is intended to launch a URL or command line. Note that the user must have rights to execute the application.

Parameter	Description
	The only parameter is the command line or URL of the application to execute.

ShowAbout

Displays the about dialog box for Unified Service Desk that contains information such as the name of the current user, the Dynamics 365 server and organization that the user is connected to, version number of the Unified Service Desk client application, and the support site URL.

ShowTab

Sets the focus on a tab (hosted control) in your agent application.

Parameter	Description
	The first line in the action call should contain the name of the hosted control to display in the foreground. Don’t use the display name of the hosted control. For more information about using this action call, see step 4 of Walkthrough 2: Display an external webpage in your agent application.

StopEventTimer

Stops an event timer.

Parameter	Description
name	Name of the event timer to stop.

Translate

Enables you to perform language translation using Microsoft Translator.

Parameter	Description
value	This is the text to translate. This value may be escaped for multi-line support. Some valid examples: `value=$Escaped("my string<br>new line\\\"my text\\\"")` `value=[[myapp.myparam]^]` `value=$Escaped([[myapp.myparam]$])` For more information about these replacement keys, see Use replacement parameters to configure Unified Service Desk.
fromlanguage	Name of the language to translate from. If this is blank, the system will attempt to detect the language of the specified value to be translated before translating. For a list of valid language values, see Translator Language Codes.
tolanguage	Name of the language to translate to. For a list of valid language values, see Translator Language Codes.
clientId	A client ID obtained from Microsoft Azure for translation services. For information about registering with Azure, see https://datamarket.azure.com.
clientsecret	A client secret obtained from Microsoft Azure for translation services. For information about registering with Azure, see https://datamarket.azure.com.

The translated value is displayed under the $Return replacement parameter.

UpdateEntity

Updates a record in Dynamics 365.

Parameter	Description
Id	The ID of the value to update. This must be the GUID of the record to update.
LogicalName	The logical name of the entity to update

Each subsequent line the parameter list contains a series of Name=Value pairs that will define your other fields to populate on update.

Entity References can be described like the following:

Param=EntityReference(“logicalname”, “id”)

OptionSetValue’s can be specified like the following:

Param=OptionSetValue(value)

Boolean’s can be described like the following:

Param=Boolean(value)

PartyList (used with email) can be described like the following:

Param=PartyList(email[“test@test.com”], er[“contact”, guid])

You can use any number of email and er entries to represent email addresses and entity references respectively.

Other values such as string values can be specified like the following:

Param=value

WorkOn

This action is equivalent to selecting a queue item from a queue and clicking the WorkOn button on the ribbon. It marks the queue item as being worked by a specific agent.

Parameter	Description
Id	This is the Id of the queueitem. See LookupQueueItem for information on how to obtain the ID for a target entity.
Action	Optional parameter allowing the administrator to specify that they wish to remove the WorkOn attribute to return it to the queue. Valid Values: Remove – Removes the WorkOn attribute and returns the item to the queue for others to work on.

This is the Id of the queueitem. See LookupQueueItem for information on how to obtain the ID for a target entity.

Action

Optional parameter allowing the administrator to specify that they wish to remove the WorkOn attribute to return it to the queue.

Valid Values:

Remove – Removes the WorkOn attribute and returns the item to the queue for others to work on.

Predefined events

Here are the predefined events that are associated with this hosted control.

DesktopReady

Occurs on startup when all the desktop initialization has completed and the connections to Dynamics 365 have been established. This event will be fired only once, and it is common to use this event to set themes and do other startup actions.

SessionActivated

Occurs whenever a session is activated.

Parameter	Description
SessionId	ID of the currently active session.
IsGlobal	Indicates whether this event applies to the global session. Returns True or False.
Activate	This is set to True.

SessionClosed

Occurs when a session is closed.

Parameter	Description
SessionId	ID of the session that was closed.
IsGlobal	Indicates whether this event applies to the global session. Returns True or False.

SessionDeactivated

Occurs when a session is deactivated.

Parameter	Description
SessionId	ID of the inactive session.
IsGlobal	Indicates whether this event applies to the global session. Returns True or False.
Activate	This is set to False.

SessionNew

Occurs when a new session is created.

Parameter	Description
SessionId	ID of the newly created session.
IsGlobal	Returns True if the new session is a global session. Otherwise, returns False.

Global Manager (Hosted Control)

In This Topic

Create a Global Manager hosted control

Predefined UII actions

Audit

CallDoAction

ClearAppBar

ClearEntityList

Close

CloseActive

CopyToClipboard

CopyToContext

CopyLogicalEntityToContext

CloseActivity

CreateEntity

CreateSession

DeleteEntity

DoRoute

DoSearch

DisplayMessage

ExecuteOnDataAvailable

ExecuteOnTimeout

ExecuteOnExpressionTrue

ExecuteScriptlet

FireEvent

GetTemplate

InvokeCTI

LaunchURL

LookupQueueItem

MoveApplicationToPanel

MoveToPanel

New_CRM_Page

Open_CRM_Page

Pause

Popup

RealignWindow

ReadSettings

RedoScreenPop

ResetLocalCache

RouteToQueue

SaveAll

SaveSetting

SetTheme

SetAppBar

SetEventTimer

SetSize

SetWindowProperty

ShellExecute

ShowAbout

ShowTab

StopEventTimer

Translate

UpdateEntity

WorkOn

Predefined events

DesktopReady

SessionActivated

SessionClosed

SessionDeactivated

SessionNew

See Also

Additional resources