The Finesse Layout XML defines the layout of the Finesse desktop, and the gadgets and components displayed on the desktop.

Use the Manage Desktop Layout gadget to upload an XML layout file to define the layout of the Finesse desktop for agents and supervisors.

Actions on the Manage Desktop Layout gadget are as follows.

• Edit the code using any of the following editors:

  • Text Editor

  • XML Editor

• View Default Layout - Displays the Cisco Finesse default layout.

• Restore Default Layout - Restores the Cisco Finesse desktop to the default layout.

• Save - Saves your configuration changes.

• Revert - Retrieves and applies the most recently saved desktop layout.

• Text Editor—A plain text editor. It is the default editor. You can use the Expand All option to see all the code details and Search text box to refine your search results.

• XML Editor—An XML editor.

  Note	You cannot add or edit comments (<!-- and -->) in the XML Editor. In this document, all the examples that are related to desktop layout are applicable for text editor.

Both the editors support the following features:

• Expand and collapse option.

• Syntax highlights and color code for the visual indication.

• Auto-complete suggestions and hints for valid elements in the tags.

The Cisco Finesse default desktop layout XML for Unified CCE and Packaged CCE contains optional gadgets and notes. The notes describe how to modify the layout for your deployment type.

Optional Live Data gadgets in the layout XML are commented out. After you install and configure Live Data, remove the comment tags from the reports that you want to appear on the desktop.

Following are the updates available in the default layout XML for Cisco Finesse desktop:

• Sample configurations for customizing desktop properties are added to the default layout (Desktop Layout) and team-specific layout (Team Resources > Desktop Layout).

  For upgraded layouts, sample configurations for customizing desktop properties do not appear by default. The administrator must copy the XML from the View Default Layout and add to the respective custom layouts.

• Horizontal Header is available in the layout configuration and the Header can be customized.

• Title and Logo of Cisco Finesse desktop can be customized.

• Desktop Chat, TeamMessage, Dialer, Agent Identity, and Non-Voice State Control are added as part of the header component.

  For upgraded layouts, TeamMessage and Desktop Chat will not appear by default. The XML must be copied from the default layout and added to the respective custom layouts. See Cisco Cisco Finesse Installation & Upgrade Guide.

• Vertical tabs in Cisco Finesse desktop are moved to collapsible left navigation bar for which the icons can be customized.

• Support for inbuilt java script components has been added.

• The ID attribute (optional) is the ID of the HTML DOM element used to display the gadget or component. The ID should start with an alphabet and can contain alphanumeric characters along with hyphen(-) and underscore(_). It can be set through the Cisco Finesse Administrative portal and has to be unique across components and gadgets.

• The managedBy attribute (optional) for Live Data gadgets defines the gadgets which manage these Live Data gadgets. The value of managedBy attribute for Live Data gadgets is team-performance. This means that the rendering of the gadget is managed by the Team Performance gadget. These gadgets are not rendered by default, but will be rendered when the options Show State History and Show Call History are selected in the Team Performance gadget.

  For upgraded layouts, the managedBy attribute will be introduced, and will have the value of the ID of the Team Performance gadget in the same tab. If there are multiple instances of Team Performance gadgets and Live Data gadget pairs, they will be associated in that order. If the ID of the Team Performance gadget is changed, the value of the managedBy attribute should also be updated to reflect the same ID for the Live Data gadgets. Otherwise, the Team Performance gadget instance will not show its respective Live Data gadgets.

• Gadgets that are hosted within a Multi-Tab gadget need to contain the ID of the Multi-Tab gadget as the value of its managedBy attribute.

• The Hidden attribute (optional) is used to support headless gadgets. When an attribute is set to hidden="true", then the gadget is loaded by the container, but will not be displayed. The default value set for the attribute is "false".

• The Hidden attribute can be used within Multi-Tab gadgets to make specific gadget tabs to appear or hide depending on the context.

• The default attribute (default="true") can be used to set a particular gadget as the default focus so that its contents are visible when hosted within a Multi-Tab gadget. The default gadget is always listed as the left most gadget.

  Note

  After the user customizes the order of the gadgets by dragging them, this attribute will no longer be supported. For more information on the Multi-Tab gadget order, see the Ordering of Multi-Tab Gadget Tabs section in Cisco Finesse Agent and Supervisor Desktop User Guide at https://www.cisco.com/c/en/us/support/customer-collaboration/finesse/products-user-guide-list.html.

• maxRows is changed from being a query parameter to an attribute.

  Example of maxRows being a query parameter:

  <gadget id="team-performance">/desktop/scripts/js/teamPerformance.js?maxRows=5</gadget>

  Example of maxRows being an attribute:

  <gadget id="team-performance" maxRows="5">/desktop/scripts/js/teamPerformance.js</gadget>

  During an upgrade it will be removed from the URL of the team performance gadget and added as an attribute. The maxRows attribute (optional) is used to adjust the height of the Team Performance gadget. If there are multiple instances of the Team Performance gadget, each instance height can be set by using this attribute. During an upgrade the height of the team performance gadget will be retained. By default the maxRows attribute value is set to 10 rows.

If any changes are made to the component IDs or URLs in the default XML layout, the following features may not work as expected.

Note that the components can be rearranged in any order to show on the Cisco Finesse desktop.

The administrator can configure the drag-and-drop and resize gadget or component features for agents and supervisors to customize their Finesse desktop.

• The drag-and-drop feature allows agents and supervisors to drag (and drop) the gadget or the component to the required position on the desktop layout.

• The resize feature allows the agents and supervisors to shrink or expand the gadget or the component to a custom size on the desktop layout.

• Each desktop tab can be customized to have a unique layout without affecting other tabs.

• When you resize the browser, based on the width of the browser, gadgets in the desktop layout are automatically rearranged one below the other to fit the available screen area.

Note	By default, the drag-and-drop and resize features are disabled. The administrator must set the enableDragDropAndResizeGadget desktop property value as true to enable these features.

The administrator can customize the desktop property value of these features through the desktop layout:

• Default layout (Desktop Layout)—In the Text Editor, remove the comment (<!—and -->) from the enableDragDropAndResizeGadget code snippet and enter the value as true to add these features to the desktop layout. For more information, see Customize Desktop Properties.

  The following is the sample code snippet, as displayed in the default Desktop Layout.

  <!-- <config key="enableDragDropAndResizeGadget" value="false"/> -->

• Team-specific layouts (Manage Team Resources > Desktop Layout)—Select a specific team and then in the Text Editor, remove the comment (<!—and -->) from the enableDragDropAndResizeGadget code snippet and enter the value as true to add these features to the team desktop layout. For more information, see Customize Desktop Properties at Team Level.

  The following is the sample code snippet, as displayed in the team Desktop Layout.

  <!-- <config key="enableDragDropAndResizeGadget" value="false"/> -->

Note

For upgraded layouts, the sample configuration for customizing desktop property (enableDragDropAndResizeGadget) doesn’t appear by default in the Desktop Layout. Administrators must copy the XML from the View Default Layout and add to the respective custom layouts. For new layouts, the sample configuration for customizing desktop property (enableDragDropAndResizeGadget) appears by default in the Desktop Layout. The administrator can also use the CLI and set the utils finesse set_propertydesktop enableDragDropAndResizeGadget to true to enable these features. For more information see Desktop Properties. If the drag-and-drop and resize gadget feature is enabled, the maximize or collapse functionality isn’t available in the Multi-Tab gadgets. Drag and reorder of gadgets inside a Multi-Tab gadget is independent of the enableDragDropAndResizeGadget property. If the property value is defined in the team-specific desktop layout (Manage Team Resources > Desktop Layout), the team-specific desktop layout takes precedence over the property value defined in the Desktop Layout and CLI. These features aren’t applicable for gadgets that don’t have a defined title. For more information, see the Gadget Limitations section in the Cisco Finesse Web Services Developer Guide at https://developer.cisco.com/docs/finesse/#!rest-api-dev-guide.

For more information, see the Cisco Finesse Agent and Supervisor Desktop User Guide at https://www.cisco.com/c/en/us/support/customer-collaboration/finesse/products-user-guide-list.html.

The administrator can set permission to allow an agent or a supervisor, who is the participant in a conference call using the Finesse desktop, to drop other agents, supervisors, or non-agents from the conference call.

The desktop property to drop participants from a conference call are:

• enableDropParticipantFor—This property is used to set permissions to allow the agents, supervisors, or both to drop other participants from the conference call.

  The possible values for the enableDropParticipantFor property are:

  • supervisor_only—(default value) Only the supervisor, who is a participant of the conference call, can drop other agents in the conference call.

  • conference_controller_and_supervisor—The supervisor who is a participant of the conference call or an agent who initiated the conference call (conference controller) can drop other participants.

  • all—Any agent or supervisor who is a participant of the conference call can drop other participants.

  For example, if the permission is set to be supervisor_only, when the supervisor barges in to a call between an agent and a customer, the supervisor is the only one who can make a request to drop the agent from the call. This leaves the supervisor on the call with the customer.

• dropParticipant—This property controls the listing of agents and non-agents in the Drop options list of participants in the Finesse desktop.

  The possible values for the dropParticipant property are:

  • agents—(default value) The agents or supervisors who are participants of the conference call are displayed in the Drop options list of participants in the Finesse desktop.

  • all—The agents, supervisors, CTI Route Point, IVR port, a device to which no agent is signed in, or a caller device in the conference call are displayed in the Drop options list of participants in the Finesse desktop.

For more information, see the Intercept a Call section in the Common Tasks chapter of Cisco Finesse Agent and Supervisor Desktop User Guide at https://www.cisco.com/c/en/us/support/customer-collaboration/finesse/products-user-guide-list.html.

Note

To enable the supervisor or call controller to drop an unmonitored extension in Cisco Unified CCE, in Release 12.0(1) or higher, set the DropAnyPartyEnabled registry key to 1 in the Dynamic Registry of the CTI server. The supervisor cannot drop a CTI Route Point, IVR port, a device to which no agent is signed in, a caller device, or other agents for whom SILENT_MONITOR is not initiated by the supervisor. For more information, see the Enable Dropping Call Participants from a Conference Call section in Cisco Contact Center Gateway Deployment Guide for Cisco Unified ICM/CCE at https://www.cisco.com/c/en/us/support/customer-collaboration/unified-contact-center-enterprise/products-programming-reference-guides-list.html.

The administrator can customize the desktop property value for this feature through the desktop layout:

• Default layout (Desktop Layout)—In the Text Editor, remove the comment (<!—and -->) from the enableDropParticipantFor and dropParticipant code snippets. Enter the appropriate value against the code snippet to control the feature using desktop layout. For more information, see Customize Desktop Properties.

  The following is the sample code snippet, as displayed in the default Desktop Layout.

  <!-- <config key="enableDropParticipantFor" value="supervisor_only"/> -->

  <!-- <config key="dropParticipant" value="agents"/> -->

• Team-specific layouts (Manage Team Resources > Desktop Layout)—Select a specific team layout, and then in the Text Editor, remove the comment (<!—and -->) from the enableDropParticipantFor and dropParticipant code snippets. Enter the appropriate value against the code snippet to control the feature using team desktop layout. For more information, see Customize Desktop Properties at Team Level.

  The following is the sample code snippet, as displayed in the team Desktop Layout.

  <!-- <config key="enableDropParticipantFor" value="supervisor_only"/> -->

  <!-- <config key="dropParticipant" value="agents"/> -->

Note

The administrator can also use the CLI utils finesse set_property webservices enableDropParticipantFor and set permission to allow an agent or a supervisor, who is the participant in a conference call to drop other agents, supervisors, or non-agents from the conference call. Enabling this capability at a an API level is a prerequisite for the desktop property changes. For more information, see Service Properties. The Dialog—Drop Participant from Conference API allows an agent or supervisor to make a request to drop other agents, supervisors, or non-agents from a conference based on the permission set by the administrator. By default, this API is only available for supervisors (based on the supervisor_only property); but the administrator can use the Finesse CLI to expand access. For more information, see https://developer.cisco.com/docs/finesse/#!rest-api-dev-guide. The Dialog—Drop Participant from Conference API and the team-specific layout must have the same value to have the expected behavior, as defined by the Finesse desktop property. If the values differ, then the most restrictive value takes precedence. The order is all, conference_controller_and_supervisor, and supervisor_only. For example, at the API level, it is restricted to be supervisor_only, and the Finesse desktop level restriction at team-specific layout is all, then the restriction at API level applies, as that is more restrictive than the desktop level. For upgraded layouts, sample configuration for customizing desktop property (enableDropParticipantFor and dropParticipant) does not appear by default in the Desktop Layout. The administrator must copy the respective code snippets of the XML from the View Default Layout and add to the respective custom layouts. For new installations, sample configuration for customizing desktop property (enableDropParticipantFor and dropParticipant) appears by default in the Desktop Layout.

Limitation

Finesse desktop cannot distinguish agents from another peripheral gateway (PG) as agents. So the agents from another PG are displayed using the same icon used for non-agents () in the Finesse desktop.

The <gadget> element in the Finesse Layout XML provides an attribute to specify alternate hosts from which the gadget can be loaded. This allows the Cisco Finesse desktop to load the gadget using a different host if the primary server is unavailable.

The alternateHosts attribute contains a comma-separated list of FQDNs that will be used if the primary-host-FQDN is unavailable.

<gadget alternateHosts="host1,host2,host3,...">
         https://<primary-host-FQDN>/<gadget-URL> 
    </gadget>

The alternateHosts attribute is only applicable for gadgets with an absolute URL. That is URLs containing the FQDN of a host, an optional port, and the complete URL path to the gadget. For example: <gadget alternateHosts="host1,host2">https://primary host/relative_path</gadget>

If loading the gadget from the primary-host fails, the Cisco Finesse container attempts to load the gadget from the alternate hosts in the order specified in the alternateHosts attribute.

The Cisco Finesse desktop may fail to load the gadget even if some of the hosts are reachable. In such cases, refresh the Cisco Finesse desktop.

When the gadget is specified with a relative URL, for example: <gadget >/3rdpartygadgets/relative_path</gadget>, the alternateHosts attribute does not apply and is ignored by the Cisco Finesse desktop.

Note	If the host serving the gadget fails after the Cisco Finesse desktop was successfully loaded, the desktop must be refreshed in order to load the gadget from an alternate host. The gadget does not implement its own failover mechanism.

Headless gadgets are gadgets which do not need a display space, but can be loaded and run like a background task in the browser. The Hidden attribute (optional) is used to support headless gadgets in the layout XML. When an attribute is set to "hidden=true", then the gadget is loaded by the container, but will not be displayed. The default value set for the attribute is "false".

You must ensure that the XML uploaded conforms to the XML schema definition for Finesse. The XML schema definition for Finesse is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cisco.com/vtg/finesse" targetNamespace="http://www.cisco.com/vtg/finesse" elementFormDefault="qualified">
   <!-- definition of version element -->
   <xs:element name="version">
      <xs:simpleType>
         <xs:restriction base="xs:double">
            <xs:pattern value="[0-9\.]+" />
         </xs:restriction>
      </xs:simpleType>
   </xs:element>
   <!--  The below elements are for common desktop header and configs -->
   <!--  Copied from: https://github5.cisco.com/ccbu-shared/common-desktop/blob/master/java/layout-manager/src/main/resources/layoutSchema.xsd -->
   <!--  If the common-desktop XSD changes, this too needs to be updated -->
   <!--  Only difference is that, column has been renamed to headercolumn, since column is alredy there in finesse desktop layout -->
   <xs:complexType name="configs">
      <xs:sequence>
         <xs:element name="config" type="config" minOccurs="0" maxOccurs="unbounded" />
      </xs:sequence>
   </xs:complexType>
   <xs:complexType name="config">
      <xs:attribute name="key">
         <xs:simpleType>
            <xs:restriction base="xs:string">
               <xs:pattern value="[a-zA-Z]*" />
            </xs:restriction>
         </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="value" type="xs:string" />
   </xs:complexType>
   <xs:complexType name="header">
      <xs:choice>
         <xs:sequence>
            <xs:element name="leftAlignedColumns" type="listOfColumns" minOccurs="1" maxOccurs="1" />
            <xs:element name="rightAlignedColumns" type="listOfColumns" minOccurs="0" maxOccurs="1" />
         </xs:sequence>
         <xs:sequence>
            <xs:element name="rightAlignedColumns" type="listOfColumns" minOccurs="1" maxOccurs="1" />
         </xs:sequence>
      </xs:choice>
   </xs:complexType>
   <xs:complexType name="component">
      <xs:sequence>
         <xs:element name="url" type="xs:string" minOccurs="1" maxOccurs="1" />
         <xs:element name="stylesheet" type="xs:string" minOccurs="0" maxOccurs="1" />
      </xs:sequence>
      <xs:attribute name="id" use="required">
         <xs:simpleType>
            <xs:restriction base="xs:string">
               <xs:pattern value=".+" />
            </xs:restriction>
         </xs:simpleType>
      </xs:attribute>
      <xs:attribute name="order">
         <xs:simpleType>
            <xs:restriction base="xs:string">
               <xs:pattern value="[0-9]{0,10}" />
            </xs:restriction>
         </xs:simpleType>
      </xs:attribute>
   </xs:complexType>
   <xs:complexType name="listOfColumns">
      <xs:sequence>
         <xs:element name="headercolumn" type="headercolumn" minOccurs="1" maxOccurs="unbounded" />
      </xs:sequence>
   </xs:complexType>
   <xs:complexType name="headercolumn">
      <xs:choice minOccurs="0" maxOccurs="1">
         <xs:element ref="gadget" />
         <xs:element name="component" type="component" />
      </xs:choice>
      <xs:attribute name="width">
         <xs:simpleType>
            <xs:restriction base="xs:string">
               <xs:pattern value="[0-9]+(px|%)" />
            </xs:restriction>
         </xs:simpleType>
      </xs:attribute>
   </xs:complexType>
   <!--  The above elements are for common desktop header and configs -->
   <!-- definition of role type -->
   <xs:simpleType name="role">
      <xs:restriction base="xs:string">
         <xs:enumeration value="Agent" />
         <xs:enumeration value="Supervisor" />
         <xs:enumeration value="Admin" />
      </xs:restriction>
   </xs:simpleType>
   <!-- definition of simple elements -->
   <xs:element name="id">
      <xs:simpleType>
         <xs:restriction base="xs:string">
            <xs:pattern value="[a-zA-Z]([-_:\.a-zA-Z0-9])*" />
         </xs:restriction>
      </xs:simpleType>
   </xs:element>
   <xs:element name="label">
      <xs:simpleType>
         <xs:restriction base="xs:string">
            <xs:minLength value="1" />
            <xs:pattern value="[^\r\n]+" />
            <!-- This regex restricts the label string from carriage returns or newline characters -->
         </xs:restriction>
      </xs:simpleType>
   </xs:element>
   <xs:element name="icon" type="xs:anyURI" />
   <xs:element name="gadget">
      <xs:complexType>
         <xs:simpleContent>
            <xs:extension base="restrictWhiteSpaces">
               <!-- <xs:attribute name="staticMessage" type="xs:string"/> -->
               <xs:attribute name="id">
                  <xs:simpleType>
                     <xs:restriction base="xs:string">
                        <xs:pattern value="[a-zA-Z]([-_a-zA-Z0-9])*" />
                     </xs:restriction>
                  </xs:simpleType>
               </xs:attribute>
               <xs:attribute name="alternateHosts" type="xs:string" />
               <xs:attribute name="managedBy" type="xs:string" />
               <xs:attribute name="hidden" type="xs:boolean" />
            </xs:extension>
         </xs:simpleContent>
      </xs:complexType>
   </xs:element>
   <xs:element name="role" type="role" />
   <xs:element name="gadgets">
      <!-- Grouping of a set of gadgets -->
      <xs:complexType>
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <!-- No limit to number of gadget URIs for now -->
            <xs:element ref="gadget" />
            <!-- URI of the gadget xml -->
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:simpleType name="restrictWhiteSpaces">
      <xs:restriction base="xs:anyURI">
         <xs:minLength value="1" />
         <xs:pattern value="\S+" />
         <!-- This regex restricts anyURI from containing whitespace within -->
      </xs:restriction>
   </xs:simpleType>
   <xs:element name="column">
      <!-- Grouping of a set of gadgets within a column -->
      <xs:complexType>
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <!-- No limit to number of gadget URIs for now -->
            <xs:element ref="gadgets" />
            <!-- URI of the gadget xml -->
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="columns">
      <!-- Grouping of a set of columns -->
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="column" minOccurs="0" maxOccurs="unbounded" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="page">
      <!-- Grouping of a set of persistent gadgets -->
      <xs:complexType>
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
            <!-- No limit to number of gadget URIs for now -->
            <xs:element ref="gadget" />
            <!-- URI of the gadget xml -->
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="tab">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="id" />
            <!-- Id of the tab selector in the desktop -->
            <xs:element ref="icon" minOccurs="0" maxOccurs="1" />
            <xs:element ref="label" />
            <!-- Label of the tab selector -->
            <xs:choice>
               <xs:element ref="gadgets" minOccurs="0" maxOccurs="1" />
               <xs:element ref="columns" minOccurs="0" maxOccurs="1" />
            </xs:choice>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="tabs">
      <!-- Grouping of tabs -->
      <xs:complexType>
         <xs:sequence maxOccurs="unbounded">
            <!-- No limit to number of tabs for now -->
            <xs:element ref="tab" />
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="layout">
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="role" />
            <!-- Type of the role -->
            <xs:element ref="page" />
            <!-- List of page gadgets -->
            <xs:element ref="tabs" />
            <!-- Grouping of tabs for this particular role -->
         </xs:sequence>
      </xs:complexType>
   </xs:element>
   <xs:element name="finesseLayout">
      <!-- Layout of the desktop -->
      <xs:complexType>
         <xs:sequence>
            <xs:element ref="version" />
            <xs:element name="configs" type="configs" minOccurs="0" maxOccurs="1" />
            <xs:element name="header" type="header" minOccurs="1" maxOccurs="1" />
            <xs:sequence maxOccurs="3">
               <!-- only support 3 roles for now -->
               <xs:element ref="layout" />
            </xs:sequence>
         </xs:sequence>
      </xs:complexType>
   </xs:element>
</xs:schema>