Customizing the Finesse desktop layout in UCCX

Sources

1. 1
   Sign-in to the Finesse administration console on Unified CCX uses the Application User ID and Application User password that were set during installation.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Sign In to Cisco Finesse Administration Console · Checked 2026-09-30
2. 2
   The Cisco Finesse administration console on Unified CCX is reached at https://<FQDN>:8445/cfadmin, only over HTTPS, using the fully qualified domain name of the server.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Sign In to Cisco Finesse Administration Console · Checked 2026-09-30
3. 3
   Cisco's guides disagree on where the call control gadget may be placed: the Unified CCX 15.0 guide says it is supported only at the page level, inside the page tags and not the tab tags, while the Cisco Finesse 15.0(1) guide says it is supported at both page level and tab level but not on multiple pages.disputed

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout (note on the call control gadget) · Checked 2026-09-30
4. 4
   The Finesse default desktop layout XML for Unified CCX contains optional tabs and gadgets for Web Chat and Email and for Advanced Supervisor Capabilities.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Default Layout XML · Checked 2026-09-30
5. 5
   The Contact Service Queue field Automatic Wrapup determines whether agents handling calls routed through that CSQ automatically enter the Wrapup state when a call ends; it is Disabled by default.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Provision of Unified CCX · Contact Service Queue configuration (field: Automatic Wrapup) · Checked 2026-09-30
6. 6
   The Contact Service Queue field Wrapup Time determines the length of the Wrapup state for that CSQ when a call ends, either enabled with a number of seconds or disabled for no limit.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Provision of Unified CCX · Contact Service Queue configuration (field: Wrapup Time) · Checked 2026-09-30
7. 7
   Unified CCX automatically creates a default team that cannot be deleted, and agents who are not assigned to any team belong to it.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Provision of Unified CCX · Teams Configuration · Checked 2026-09-30
8. 8
   Drag-and-drop and resize of gadgets are disabled by default and are enabled by setting the desktop property enableDragDropAndResizeGadget to true.

   Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · Drag-and-Drop and Resize Gadget or Component · Checked 2026-09-30
9. 9
   The desktop layout can be edited in either of two editors in the administration console, Text Editor or XML Editor.

   Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout · Checked 2026-09-30
10. 10
    The team-resource, workflow, reason and phone-book behaviour documented in the Cisco Finesse 15.0(1) Administration Guide probably applies to the Finesse embedded in Unified CCX 15.0, because the Unified CCX 15.0 guide's Cisco Finesse chapter has sections with the same headings, but the numeric limits and code ranges may differ on Unified CCX.inferred

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Chapter section list: Manage Phone Books; Manage Reasons; Manage Team Resources; Manage Workflows · Checked 2026-09-30
11. 11
    When Force Wrap-Up reason is configured, agents must select a Wrap-Up reason before changing state after the call ends.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Wrap-Up Reasons (Force Wrap-Up Reason) · Checked 2026-09-30
12. 12
    A tab on the Finesse desktop can have up to four columns, with the gadgets for each column placed inside that tab's columns tags.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout · Checked 2026-09-30
13. 13
    The 3rdpartygadget account is used to upload third-party gadgets to the Finesse server; its password is set with the CLI command utils reset_3rdpartygadget_password, must be 5 to 32 characters without spaces or double quotes, and is set on each server separately because it is not synchronized.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Third-Party Gadgets · Manage Third-Party Gadgets chapter, 3rdpartygadget Account · Checked 2026-09-30
14. 14
    Third-party gadgets for Finesse on Unified CCX are hosted either on the Cisco Finesse server through the 3rdpartygadget web application or on an external web server.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Gadgets and Components · Checked 2026-09-30
15. 15
    Gadgets are listed in the desktop layout with the gadget tag, whose content is the URL of the gadget XML file; to add a gadget to a tab, its gadget element is added inside that tab's gadgets tag.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · Gadgets and Components; Update Default Desktop Layout · Checked 2026-09-30
16. 16
    Third-party gadget files are uploaded by SFTP to the /files directory of the 3rdpartygadget account and are then referenced in the layout XML by a path of the form /3rdpartygadget/files/<name>.xml.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Third-Party Gadgets · Manage Third-Party Gadgets chapter, upload third-party gadgets · Checked 2026-09-30
17. 17
    Third-party gadgets uploaded to the Finesse server must be .xml files; .jsp files cannot be used.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Third-Party Gadgets · Manage Third-Party Gadgets chapter, third-party gadget limitations · Checked 2026-09-30
18. 18
    A saved change to the default Finesse desktop layout takes effect after 3 seconds, but agents who are signed in when the change is made must sign out and sign in again to see it.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout · Checked 2026-09-30
19. 19
    The Finesse Layout XML defines the layout of the Finesse desktop and the gadgets and components displayed on it, and it is edited on the Desktop Layout tab of the administration console.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Manage Desktop Layout; Finesse Desktop Layout XML · Checked 2026-09-30
20. 20
    The commented Live Data gadget examples in the Unified CCX default layout XML use the placeholder host my-cuic-server.com, which must be replaced with the fully qualified domain name of the Intelligence Center server, and the HTTPS versions of the Live Data gadgets are to be used.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Default Layout XML (comments in the default layout) · Checked 2026-09-30
21. 21
    Cisco Finesse 15.0(1) supports a total of 200 Not Ready reason codes, a maximum of 100 global and 100 team codes, with labels of at most 40 characters.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Not Ready Reason Codes · Checked 2026-09-30
22. 22
    The total number of contacts per agent across all phone books is limited to 6000, and an import list containing more than 6000 contacts is rejected with an error message.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Phone Books · Phone Books and Contacts; Import Contacts · Checked 2026-09-30
23. 23
    Importing contacts replaces all the contacts in a phone book with the new list, which must be a comma separated values file with the headers in the first line.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Phone Books · Import Contacts · Checked 2026-09-30
24. 24
    Cisco Finesse 15.0(1) supports 10 global phone books and 300 team phone books, with 50,000 contacts system-wide, before any engineering special that raises those figures.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Phone Books · Phone Books and Contacts · Checked 2026-09-30
25. 25
    Finesse configuration changes are permitted only on the primary Unified CCX server; the Finesse administration console on the secondary server is read-only.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Sign In to Cisco Finesse Administration Console · Checked 2026-09-30
26. 26
    Customized desktop properties are set only in the configs section of the layout XML, as config elements with a key and a value, and are not role-specific.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · Customize Desktop Properties · Checked 2026-09-30
27. 27
    Changes to reasons take effect on the agent or supervisor desktop after three seconds, but agents who are signed in when the changes are made must sign out and sign in again.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Wrap-Up Reasons; Not Ready Reason Codes; Sign Out Reason Codes (exact subsection not returned) · Checked 2026-09-30
28. 28
    The Cisco Finesse 15.0(1) Administration Guide, written for Unified CCE, says a reason code can be any value between 1 and 65535 and must be unique; this packet could not confirm the range that applies on Unified CCX.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Not Ready Reason Codes; Sign Out Reason Codes · Checked 2026-09-30
29. 29
    Restore Default Layout returns the desktop layout to the shipped default, and because an upgrade does not update a changed default layout, it is also how the latest default layout is obtained after an upgrade.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout · Checked 2026-09-30
30. 30
    In the desktop layout editor, Revert returns the editor to the last saved desktop layout.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · Update Default Desktop Layout · Checked 2026-09-30
31. 31
    The layout XML is divided by role: XML for an agent-facing tab is added within the tabs tags under the <role>Agent</role> tag, and supervisor-facing XML goes under the supervisor role.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Default Layout XML; Update Default Desktop Layout (exact subsection not returned) · Checked 2026-09-30
32. 32
    When a desktop layout is saved, Finesse validates that the XML is valid XML syntax and conforms to the Finesse schema.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · Update Default Desktop Layout · Checked 2026-09-30
33. 33
    Cisco Finesse 15.0(1) supports 200 Sign Out reason codes, 100 global and 100 team, with labels of at most 40 characters.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Sign Out Reason Codes · Checked 2026-09-30
34. 34
    A tab ID in the layout XML must start with a letter and may contain alphanumeric characters, hyphens and underscores.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Desktop Layout · XML Schema Definition · Checked 2026-09-30
35. 35
    A saved custom team layout replaces the default layout for that team after 10 seconds, and a supervisor or agent who is signed in when it is saved does not get it until signing out and signing in again.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Assign Custom Desktop Layout to Team · Checked 2026-09-30
36. 36
    Clearing the Override System Default check box discards the team's XML changes and the editing pane reverts to the default desktop layout XML.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Assign Custom Desktop Layout to Team · Checked 2026-09-30
37. 37
    Only Not Ready reason codes defined in the Manage Reason Codes (Not Ready) gadget as available to teams, not global, can be assigned to a team.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Team Resources (Reason Codes (Not Ready) tab description) · Checked 2026-09-30
38. 38
    To give a team its own layout, select the team in the Manage Team Resources gadget, open Desktop Layout, and select the Override System Default check box, which makes the XML (pre-filled with the default layout) editable.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Assign Custom Desktop Layout to Team · Checked 2026-09-30
39. 39
    Only phone books defined in the Manage Phone Books gadget as available to teams can be assigned to a team on the Phone Books tab of Manage Team Resources.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Team Resources (Phone Books tab description) · Checked 2026-09-30
40. 40
    A desktop property value defined in a team-specific desktop layout takes precedence over the value defined in the default Desktop Layout and over the value set by CLI.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Customize Desktop Properties at Team Level · Checked 2026-09-30
41. 41
    The Manage Team Resources gadget has six tabs for a selected team: Desktop Layout, Phone Books, Reason Codes (Not Ready), Reason Codes (Sign Out), Wrap-Up Reasons and Workflows.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Team Resources · Checked 2026-09-30
42. 42
    Workflows assigned to a team on the Workflows tab of Manage Team Resources run in the order they are listed, and the up and down arrows change that order.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Team Resources · Assign Workflows to Team · Checked 2026-09-30
43. 43
    In Unified CCX a team is a group of agents who report to the same supervisor, with one primary supervisor and optional secondary supervisors, and teams are created in Unified CCX Administration under Subsystems > RmCm > Teams.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Provision of Unified CCX · Teams Configuration; Create a Team · Checked 2026-09-30
44. 44
    The same Unified CCX 12.5 tech note restarts the Cisco Unified CCX Notification Service, Cisco Finesse Tomcat and the Unified CCX Socket.IO Service after changing the layout, then verifies by signing in to the Finesse desktop and confirming the new tab appears.

    Configure CUIC Historical Report Gadgets in Cisco Finesse · Configure (restart services); Verify · Checked 2026-09-30
45. 45
    A Cisco tech note for Unified CCX 12.5 adds a custom gadget by resetting the 3rdpartygadget user password from the CLI, uploading the gadget XML file by SFTP to /3rdpartygadget/files, and then adding the gadget path inside a new tab in the Finesse desktop layout XML.

    Configure CUIC Historical Report Gadgets in Cisco Finesse · Configure (steps for uploading the gadget XML and editing the desktop layout) · Checked 2026-09-30
46. 46
    The Finesse guide gives utils service restart Cisco Finesse Tomcat as the way to clear a stale cached copy of a third-party gadget after it has been changed.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Third-Party Gadgets · Manage Third-Party Gadgets chapter, upload third-party gadgets (note on caching) · Checked 2026-09-30
47. 47
    Cisco states the Finesse desktop is tested to perform well with an average of 20 gadgets per desktop across all tabs; this is a tested figure, not an enforced maximum.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Live Data Gadgets (as reported by extraction; the sentence may sit in the default layout XML notes) · Checked 2026-09-30
48. 48
    The Unified CCX Finesse user guide tells agents that the functionality available on the desktop depends on what the administrator configured; for example, if no Wrap-Up Reasons are defined the agent cannot choose one.

    Cisco Finesse Agent and Supervisor Desktop User Guide for Cisco Unified Contact Center Express, Release 15.0 - Cisco Finesse Desktop Interface · Cisco Finesse Desktop Interface chapter (exact heading not returned) · Checked 2026-09-30
49. 49
    The version tag of the desktop layout XML cannot be edited.

    Cisco Unified Contact Center Express Administration and Operations Guide, Release 15.0 - Cisco Finesse · Update Default Desktop Layout · Checked 2026-09-30
50. 50
    Finesse has two workflow action types, Browser Pop and HTTP Request, created in the Manage Workflow Actions gadget, and an action's Handled By field chooses between the Finesse Desktop and Other (a third-party gadget).

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Workflows and Workflow Actions; Add Browser Pop Workflow Action · Checked 2026-09-30
51. 51
    A workflow is defined with a name of up to 40 characters, a trigger chosen in the When to perform Actions list, up to five conditions applied as all-met or any-met, and an ordered list of actions.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Add Workflow · Checked 2026-09-30
52. 52
    A workflow applies only to the first call that matches its trigger, and when several workflows are configured for a team the workflow engine evaluates them in the configured order.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Workflows and Workflow Actions · Checked 2026-09-30
53. 53
    An HTTP Request workflow action is defined by the fields Handled By, Method, Location, Content Type, URL and Body.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Add HTTP Request Workflow Action · Checked 2026-09-30
54. 54
    Cisco Finesse 15.0(1) supports 100 workflows and 100 actions per Finesse system, 20 workflows per team, five conditions per workflow, five actions per workflow and five variables per action.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Workflows and Workflow Actions · Checked 2026-09-30
55. 55
    A Finesse workflow does not run until it is assigned to a team.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Add Workflow · Checked 2026-09-30
56. 56
    When an agent refreshes the browser the workflow engine treats the call as newly arrived or newly made, so an HTTP Request action in the workflow is sent again on refresh.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Workflows and Workflow Actions · Checked 2026-09-30
57. 57
    The voice events that can trigger a Finesse workflow include when a call arrives, when a call is answered, when a call ends and when making a call.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Workflows and Workflow Actions · Checked 2026-09-30
58. 58
    Finesse does not validate the URL entered in a Browser Pop action; variable tags can be inserted into the URL and sample data entered for each variable to preview it.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Add Browser Pop Workflow Action · Checked 2026-09-30
59. 59
    In a Browser Pop action the window name is limited to 40 characters and may be blank; if it is blank a new window opens every time the action runs, and whether it opens as a window or a tab depends on browser settings.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Workflows · Add Browser Pop Workflow Action · Checked 2026-09-30
60. 60
    Cisco Finesse 15.0(1) supports a maximum of 100 global and 1500 team Wrap-Up reasons, with no more than 100 Wrap-Up reasons assigned to any one team, and Wrap-Up reasons can be global to all agents or limited to specific teams.

    Cisco Finesse Administration Guide, Release 15.0(1) - Manage Reasons · Wrap-Up Reasons · Checked 2026-09-30

Documents

Cite this page

WarmTransfer. (2026, September 30). Customizing the Finesse desktop layout in UCCX. WarmTransfer. https://warmtransfer.net/guides/uccx-finesse-desktop-setup

@misc{warmtransfer-uccx-finesse-desktop-setup,
  title  = {Customizing the Finesse desktop layout in UCCX},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/guides/uccx-finesse-desktop-setup},
  note   = {Verified 2026-09-30}
}