Global Manager (Hosted Control)

Artykuł
08/19/2015

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 CRM 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

All the four sample applications for Unified Service Desk come preconfigured with an instance each of the Global Manager hosted control type. For information about the sample applications, see TechNet: Sample Unified Service Desk applications.

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 CRM 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 CRM record data through the web services. These can be used during configuration to perform advanced functions in CRM.

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

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`.

New_CRM_Page

Creates a page for creating a new CRM 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.

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.

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.

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.

Parameter	Description
milliseconds	The time, in milliseconds, to indicate the amount of time to wait before this action expires, and is cancelled. 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 cancelled. 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 is not 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 a specified time elapses. A time-out value is required to indicate when the sub actions should be run.

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 is not 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.

Parameter	Description
milliseconds	The time, in milliseconds, to indicate the amount of time to wait before this action expires and is cancelled. 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 cancelled. 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 is not 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

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.

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.

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.

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.

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, CRM Message will be used.

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.

DoSearch

Calls the CRM web services using FetchXML is defined as an entity search in Unified Service Desk, and the entity search name is passed as a parameter for this action call. For more information about 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

When you call this action, the $Return replacement parameter will display the number of records found and stored in EntityList as a result of this search. For more information, see $Return.

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. Do not 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.

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.

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.

SetTheme

Applies a theme to modify the layout and/or look and feel of components of the user interface. For more information, see 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 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.

SaveSetting

Stores a user specific setting.

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

ReadSettings

Reads the previously saved settings from the $Settings section.

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

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.

RouteToQueue

Routes an entity to a queue in CRM.

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.

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.

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.

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.

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.

InvokeCTI

Simulates CTI events

Parameter	Description
type	This is the type of CTI event, such as phonecall and 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.

RedoScreenPop

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

ShellExecute

This action is intended to launch a URL or command line. NOTE: 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.

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.

CreateEntity

Creates a new record in CRM.

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”)

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

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

UpdateEntity

Updates a record in CRM.

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

CloseActivity

Closes an activity record in CRM.

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.

DeleteEntity

Deletes a record in CRM.

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.

CreateSession

Creates a session.

ExecuteScriptlet

Executes the specified scriptlet.

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

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.

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.

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.

SetWindowProperty

Sets the window state for the client application main window.

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

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.

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.

SetEventTimer

Sets an event timer to start.

Parameter	Description
name	Name of the event timer.

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.

ShowAbout

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

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 CRM 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.

Udostępnij za pośrednictwem

Global Manager (Hosted Control)

In This Topic

Create a Global Manager hosted control

Predefined UII actions

CopyToClipboard

New_CRM_Page

Open_CRM_Page

Popup

Close

ExecuteOnDataAvailable

ExecuteOnTimeout

ExecuteOnExpressionTrue

FireEvent

MoveToPanel

SetSize

SaveAll

DisplayMessage

ClearEntityList

DoSearch

ShowTab

CloseActive

CallDoAction

SetTheme

SaveSetting

ReadSettings

DoRoute

RouteToQueue

LookupQueueItem

WorkOn

Pause

CopyToContext

CopyLogicalEntityToContext

InvokeCTI

RedoScreenPop

ShellExecute

Audit

CreateEntity

UpdateEntity

CloseActivity

DeleteEntity

CreateSession

ExecuteScriptlet

ResetLocalCache

GetTemplate

MoveApplicationToPanel

SetWindowProperty

SetAppBar

ClearAppBar

SetEventTimer

StopEventTimer

Translate

ShowAbout

Predefined events

DesktopReady

SessionActivated

SessionClosed

SessionDeactivated

SessionNew

See Also

Concepts

Other Resources

Dodatkowe zasoby