00 · Header

T4 · Webex Contact Center Enterprise

Finesse Desktop & Gadgets

Cisco Finesse is the browser desktop in the Unified CCE and Webex CCE guides. The layout is XML. Failover is a CTI reconnect, not a gadget refresh.

Expand all sections

01 · Executive summary

Five lines, then why it matters

• Finesse gadgets are applications inside one desktop. Third-party gadgets can live on the 3rdpartygadget web application or on an external server. [cite:1]
• REST calls from a gadget to an external service are proxied through Shindig. The gadget still has to authenticate to that third-party service itself. [cite:1]
• The layout XML has an Agent role and a Supervisor role. A supervisor tab is added under the Supervisor tag. [cite:1]
• Finesse misses failover detection after three missed CTI heartbeats. The heartbeat interval is five seconds. [cite:4]
• If a desktop client’s reconnect takes longer than 2 minutes, Finesse signs the agent out. [cite:6] re-check

02 · Architecture map

Layout XML, then the CTI pair

• 1One XML file, two roles
• 2Relative path or absolute URL
• 3A-side and B-side CTI

flowchart LR
  XML[Layout XML] --> Desk[Finesse desktop]
  Desk --> CTIA[CTI A]
  Desk --> CTIB[CTI B]
  Gadget[3rdpartygadget] --> Desk

03 · Core concepts

XML, proxy, and duplex

Failover timings the guide prints

04 · Ecosystem

What sits beside the desktop

Glossary

Finesse

The OpenSocial gadget container documented in the Cisco Finesse Administration Guide, Release 15.0(1). [cite:1]

Manage Desktop Layout

The administration gadget used to upload the XML layout for agents and supervisors. [cite:1]

3rdpartygadget

The web application on the Finesse server that hosts uploaded third-party gadget files. [cite:1]

Shindig

The backend that proxies gadget REST calls so the browser does not make a cross-origin call directly. [cite:1]

CTI server

Runs on the peripheral gateway. Finesse is configured with an A side and a B side. [cite:5]

Peripheral ID

The Agent PG routing client ID. The guide says it should be the same value for the A-side and B-side CTI servers. [cite:5]

OUT_OF_SERVICE

Finesse state while CTI failover is in progress. [cite:4]

IN_SERVICE

Finesse state after it reconnects to a CTI server and will again answer clients and publish events. [cite:4]

Manage Digital Channels

A gadget path the default layout comments include for digital channels. The what’s-new page points at the gadget user guide. [cite:1] [cite:7]

FIPPA

Finesse IP Phone Agent. The March 2022 VPN-less note says FIPPA is not supported on that internet path. [cite:7] re-check

Multi-tenant Agent Desktop

The Webex Contact Center desktop in T3-R04. It is not this XML layout. [cite:8]

Conference caveat

An agent on a conference with devices that are not other agents or supervisors can see unpredictable desktop notifications across a failover. Phone operations can continue. The desktop returns to usual after the agent drops the conference. [cite:4]

Mind map

mindmap
  root((Finesse))
    Layout XML
    CTI pair
    Third-party gadgets

Sister matrix

Integration edges

Bridges

Future hooks

• Canon plan: re-read the failover timings when a Finesse guide newer than the December 12, 2025 update is published.
• The 2-minute sign-out is in the Solution Design Guide updated March 15, 2025. Keep the re-check until that chapter is inside 12 months.
• Unhide CCAI gadgets only after the Contact Center AI gadget guide for that release says the service is on.

Ecosystem troubleshooting

05 · Flow

From XML upload to a failover

06 · Config

Settings you can cite

1. Open Manage Desktop Layout and upload an XML file. Keep an Agent role block and a Supervisor role block. [cite:1]
2. For a gadget file you uploaded to the Finesse server, add a relative path under /3rdpartygadget/files/. [cite:3]
3. For a gadget on another host, use a fully qualified URL. [cite:2]
4. On the primary Finesse server, open Contact Center Enterprise CTI Server Settings. Enter A-side host and port, B-side host and port, and the Agent PG peripheral ID. Use the same peripheral ID on both sides. [cite:5]
5. The CTI host is typically the PG, because the CTI server runs on the PG. B-side port accepts 1 through 65535 and must match the CTI server setup. [cite:5]
6. Use Test Connection. One side succeeding is valid. Both succeeding together is a problem to fix. The test does not prove the peripheral is online. [cite:5]
7. After any CTI settings change, restart Cisco Finesse Tomcat on all nodes. Do that when agents are signed out. They must sign in again after the restart. [cite:5]

Screenshot slot: Manage Desktop Layout with hostnames and gadget URLs redacted.

07 · Limits

Timers and rules

08 · Troubleshooting

Layout, proxy, and CTI

09 · Self-question ladder

Twelve rungs

10 · Lab

Paper lab: read a layout and a CTI pair

• Goal: mark a Finesse design packet without signing into a production server.
• Prereq: a redacted layout XML and a CTI settings sheet. [cite:1]
• Step 1. Find the Agent role and the Supervisor role. Expected: both exist.
• Step 2. Classify each gadget URL as relative or absolute.
• Step 3. Confirm A-side host, B-side host, and one shared peripheral ID.
• Step 4. Write the failover states: OUT_OF_SERVICE with 503, then IN_SERVICE.
• Evidence: the example path /3rdpartygadget/files/ if the file is on-box, and the heartbeat of three misses at five seconds.
• Break it: remove the B-side host. Recovery: put it back. Production requires both sides.
• Reflection: which timer came from the December 2025 admin guide, and which came from the March 2025 design guide?

11 · Quiz

Twelve checks

12 · Audio

Slots for Studio

13 · Interview

Oral answers

30 seconds. Finesse is an OpenSocial desktop. I upload one XML layout with an Agent role and a Supervisor role. Gadgets on the server use a relative path under 3rdpartygadget. Gadgets elsewhere use an absolute URL.

2 minutes. CTI failover needs duplex Unified CCE and both CTI sides. The CTI server runs on the PG, and both sides use the same peripheral ID. Three missed five-second heartbeats, or a dead socket, moves Finesse to OUT_OF_SERVICE. Clients get 503 and no events. Finesse alternates servers until one connects, then publishes the last call and agent state. A call that begins and ends inside that window is not published. Test Connection may fail on the passive side. Both sides succeeding at once is the case I investigate.

30 seconds, auth. Shindig proxies the REST call. The gadget still logs into the third-party service itself.

2 minutes, timers I date. The heartbeat and the 503 are in the administration guide updated December 12, 2025. The two-minute desktop sign-out is in the Solution Design Guide updated March 15, 2025, so I mark it re-check. The VPN-less exclusions for FIPPA and NAT are a March 2022 what’s-new note, also re-check.

What you will not say. You will not configure this XML from the multi-tenant Agent Desktop screen. That desktop is a different product.

14 · Citations

Ledger

Retrieved 2026-10-14. Study notes from public sources.

1. Cisco Finesse Administration Guide, Release 15.0(1), Manage Desktop Layout — cisco.com — updated December 12, 2025 — Manage Desktop Layout. OpenSocial XML. Shindig proxy. Agent and Supervisor roles. 3rdpartygadget hosting.
2. LayoutConfig — developer.cisco.com Finesse — LayoutConfig. Relative path on the Finesse server. Fully qualified URL off the server.
3. Cisco Finesse Administration Guide, Release 15.0(1), Manage Third-Party Gadgets — cisco.com — Manage Third-Party Gadgets. Example path /3rdpartygadget/files/HelloWorld.xml.
4. Cisco Finesse Administration Guide, Release 15.0(1), Cisco Finesse Failover Mechanisms — cisco.com — updated December 12, 2025 — Failover mechanisms. Duplex, OUT_OF_SERVICE, 503, five-second heartbeat, 35–75 second guideline, conference caveat, non-voice WORK state.
5. Cisco Finesse Administration Guide, Release 15.0(1), Manage System Settings — cisco.com — CTI Server Settings. A and B mandatory in production. Same peripheral ID. Test Connection. Tomcat restart.
6. Solution Design Guide for Cisco Unified Contact Center Enterprise, Release 15.0(1), High Availability and Network Design — cisco.com — updated March 15, 2025 — High availability. Reconnect longer than 2 minutes signs the agent out. re-check
7. What’s new for administrators in Webex Contact Center Enterprise — help.webex — article nhy3hvdb — help.webex.com article nhy3hvdb. Digital channels. VPN-less Finesse considerations. Windows 11 client note. 9-1-1 pointer. re-check
8. Webex Contact Center architecture — help.webex — article utqcm7 — help.webex.com article utqcm7. Multi-tenant architecture. Not the Finesse XML guide.
9. Webex WFO: Feature Specific SKUs — help.webex — article py6u9h — help.webex.com article py6u9h.
10. Cisco Unified Contact Center Enterprise Reporting User Guide, Release 15.0(1) — cisco.com — CUIC chapter. Reporting platform boundary. re-check

15 · Re-engineer later

Still open

• Open questions: exact Agent PG 12.6 failover range beyond the “varies” sentence already in the failover chapter; live gadget-property screen after the July 2023 drag-and-drop note.
• Facts still marked re-check: the 2-minute sign-out, the March 2022 VPN-less exclusions, and the July 2023 Windows 11 sentence.
• Assets missing: redacted layout screenshot, audio, exported SVGs.
• Ideas for v1.0: a one-page XML skeleton with the two roles and no sample credentials.
• Next review: re-read the failover chapter if Cisco updates it after December 12, 2025.