Global Manager (Hosted Control)
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 Dataverse 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 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.
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.
In the New Hosted Control screen, under the Unified Service Desk area, select Global Manager from the Unified Service Desk 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 Dataverse using the Connection Manager hosted control. For information about other General fields, see Create or edit a hosted control.
Next, select the Language Services tab to 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 Dataverse record data through the web services. The predefined actions can be used during configuration to perform advanced functions in Dataverse.
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 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 | 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 | Panel to find the active application, if no application is specified. |
| action | Action to call on the hosted control. |
| data | Data parameter to pass to the action. |
| application | Hosted control name for which you want to execute an action call. If the hosted control name 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 the search results 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 the model-driven apps.
| 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 parameter and values:
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 the model-driven apps.
| Parameter | Description |
|---|---|
LogicalName |
The logical name of the entity to create the record. |
RunAsync |
Set the parameter to True to create the entity record asynchronously so that Unified Service Desk is not blocked and remains responsive during the action execution. Note: The associated sub-action calls and subsequent action calls for the CreateEntity action do not wait for the asynchronous create operation to complete. So, you must ensure that if you are running the CreateEntity action asynchronously, the sub-action calls that depend on the created record are configured to execute only when the target record is complete. This can be achieved using the ExecuteOnDataAvailable action on the Global Manager hosted control. |
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.
| Parameter | Description |
|---|---|
| BackGround | Set the value of the parameter to True. A session is created but the focus is not changed to the new session right away. All the sub actions on this action call are then executed only when you manually switch to this session. |
| SessionName | Name of the session tab for the newly created session. This parameter is dependent on the BackGround parameter. |
DeleteEntity
Deletes a record in the model-driven apps.
| Parameter | Description |
|---|---|
| Id | The ID (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 Dataverse 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 the search results 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: 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 | Text displayed in the message box. If this parameter is not specified, any remaining text (remainder parameter) or empty string will be used. |
| caption | Caption displayed in the message box. If no caption is specified, Dataverse 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]] |
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 |
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(); |
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 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. |
Popup
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 the model-driven apps.
| 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: Use themes to 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 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 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, Dataverse 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. |
TriggerEdgeWebView2PoolCleanUp
Cleans up the Edge WebView2 pool.
TriggerChromePoolCleanUp
Cleans up the Chrome pool.
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 Azure for translation services. For information about registering with Azure. |
| clientsecret | A client secret obtained from Azure for translation services. For information about registering with Azure. |
The translated value is displayed under the $Return replacement parameter.
UpdateEntity
Updates a record in the model-driven apps.
| 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 emails 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. |
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 Dataverse 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. |
See also
UII actions Events View predefined actions and events for a hosted control View embedded help for actions and events Unified Service Desk Configuration Walkthroughs Hosted control types and action/event reference