Showing results for 
Search instead for 
Did you mean: 

Configuration of Call Peripheral Variables and the Expanded Call Context (ECC) Finesse



Use the Set Enterprise Call Info step to send data from one part of your system to another. You can set these
enterprise call variables:

  • Call.CallerEnteredDigits
  • Call.PeripheralVariable1 to Call.PeripheralVariable10
  • Call.AccountNumber
  • Expanded Call Context (ECC) Variables

Why ECC?

A peripheral variable can only contain 40 characters, an ECC variable can contain 210 characters. So it gives the user an extra customization abilities which are not possible with the General Call Peripheral variables.

Also, if the requirement for passing enterprise variables is more than 10, then the need for ECC arises.


Knowledge on the working of the Set Enterprise Call Info Step.


Script Editor

UCCX 10.x or later with Finesse

Components Used

UCCX 10.x or Later

Script Editor

Web Browser for Finesse Login.



Step 1. Define an Expanded Call Variable for the Layout

Create a CCX script with call queuing capability and the Get Call Contact Info and Set Enterprise Call Info steps. As part of the script creation process, define the script variables.

CcxScript.pngExample CCX script.


Example CCX script variables.

Navigate to Settings Expanded Call Variables to create Expanded Call Context (ECC) variables. To distinguish between the multiple layouts created in Finesse, there must be an ECC variable called user.layout. The value for this variable is set with the Set Enterprise Call Info step and that defines which Finesse call variable layout will display the call variables. If no user.layout variable exists, the default layout will be used.

Additionally, any other ECC variables are specified here.


Example CCX script ECC variables.

Caution: If the ECC user.layout variable is configured instead as user.Layout (capital letter L), the custom layout in the Finesse desktop will display on the agent desktop, but the FIPPA phone layout will revert to the default call variable layout. 

Caution: If the ECC user.layout variable is not configured, only the default Finesse call variable layout will be used.

Step 2. Collect Call Information

It is common to collect information about the call via the Get Call Contact Info step. In this example, the calling and original called number are collected.

After placing the Get Call Contact Info step, right click on Get Call Contact Info and select Properties. 

Define the attributes to collect by mapping the attribute to a variable.



Step 3. Define Call Variables

Set the variables in the Set Enterprise Call Info step. Right click on Set Enterprise Call Info and select Properties.

The following call variables can be set:

  • Call.CallerEnteredDigits

  • Call.PeripheralVariable1 to Call.PeripheralVariable10

  • Call.AccountNumber

  • Expanded Call Context (ECC) Variables

A peripheral variable can only contain 40 bytes, while an ECC variable can contain 210 bytes. An American Standard Code for Information Interchange (ASCII) character is 1 byte in length. Additionally, if more call variables than those predefined in the General tab are needed, use ECC variables.


Note: Call.PeripheralVariableX corresponds to the variable "callVariableX" in the Cisco Finesse Administration page, where X is an integer ranging from 1-10.

In the Expanded Call Variables tab, map values to the ECC variables. 


Step 4. Create an Application That Uses the Script

Navigate to the Cisco Unified CCX Administration page > Applications Script Management and upload the script.

Navigate to the Cisco Unified CCX Administration page > Applications Application Management and create an application that uses the script. Do not forget to define any necessary script parameters. In this example, the CSQ is a parameter that must be manually input on the application page.

Note: Full configuration of the application, trigger, call control groups, agents, skills, other Finesse configuration, FIPPA, etc is outside the scope of this document. For details on this, refer to the UCCX Administration guides.

Step 5. Configure Finesse Layout

Create a custom layout in the Finesse page by clicking New.

Specify the number of variables and name the variables on the left and right columns.

Specify which variables are passed from the script to be displayed on Finesse. The variable dropdowns contain all variable options that can be passed to Finesse. 

To specify ECC variables, select Custom... from the dropdown option:


All user-defined ECC variable names created in any UCCX script must start with user. (read: user<dot>), so the Finesse ECC variable configuration will always have user as the first part of the variable name.


 The final configured example layout.


Troubleshoot / Common Issues



Hi Arun,

Thanks for Sharing great document. 

However, I followed the steps for creating ECC variable(pic attached) and passing them through Set Enterprise Call Info Step(pic attached) and also add them on my Finesse Admin Call Variable Layout (pic attached). But When Call comes in I don't see any output to those variable in our Finesse Agent Desktop.

Note: Just to be noted, the value/variable that we are assigning to ECC variable are getting populated with desired values before the Set Enterprise Call Info Step

I am Using UCCX 10.5 


M Taha


Actually it did work.

I was hitting the wrong trigger ;)


M Taha

Cisco Employee

Glad that you got it working!!




Thx for this document, it works.


Cisco documetation is wrong. See attachement.


Thank Arundeep - this really helped me on my first Finesse deployment!



I have a customer migrating from CAD to Finesse. They are using Set Enterprise call variables with CAD today and have three custom variables they are pushing to the CAD desktop.


Since with Finesse, I need to prefix these three variables with 'user', can I add the Finesse 'user' prefixed variables to the same Set Enterprise Call Info setup alongside the existing CAD variables?  

Will it hurt to have both in the same Set Enterprise Call Info ?  The Set Enterprise Call Info step for CAD has the 'user.layout', so I am not sure if that will impact Finesse.

Once we are cutover to Finesse, I can remove the CAD variables.

I'm running UCCX 10.6.1.


Thanks, it worked for me as well.


Yes, you can set it to both versions for the transition period.

I.E. variable "Custom1" and "userCustom1" are separate variables but you can set both of them to the same value, Agent Desktop will continue to use "Custom1" where "userCustom1" is used by Finesse.

Also, any custom gadget will need to access the variable using the dialog.getMediaProperties().userCustom1 interface in the finesse js library.

The only impact will be the amount of java memory used in the heap for each session, which is unlikely to become an issue outside of very busy/complex environments.

It is also important to note that you cannot use user.layout in finesse since the javascript would see layout as a property of the object "user".  If you use that variable, you can make a new one (defining it in CDA is actually not necessary) named userLayout (or whatever) and assign it the same value within the script.


Hi, Eric,

I have Call.AccountNumber (general Enterprise Call Info) used for scripts. However, I could not find it in Finesse admin page. Also I could not find ANI and DNIS. 

Further, if I could not define user.layout in script and send it to Finesse, it is not possible to have different call variable layout for different queues, correct?




You can use variables without a custom finesse gadget as long as they either appear in the drop-down box for variables in the manage call variables layout section of finesse admin, or are formatted as user<variablename>.

user.layout is not formatted correctly.  If you want to load user.layout, you have to make a new variable in your script called userlayout (without the '.') and add it as a custom variable from the dropdown.  You then need to save that information into the new variable in the script using "set enterprise call info" step

So if you want to use a variable not explicitly defined on the list, it needs to be saved as (for example) userDNIS or userANI or userAccountNumber in the script's "set enterprise call info" step(s).

Alternatively, you can grab variables (so long as they don't have a '.' in the variable name) using a custom gadget using the dialog.getMediaProperties().<variable> function made available through the finesse.js library.


Hi, Eric,

Thanks. From the default list, there are not ANI, DNIS and AccountNumber anymore as in desktop administrator for CAD. 

I could redefine ECCs as custom variables in Finesse admin. But there is no layout list concept anymore, so as I asked in previous message, it is not possible to have different call variable layouts based on different scripts/applications. Is that correct?




Correct.  If you want a layout to be customized based on the value of a variable you'll have to write a custom gadget.


Hi, Eric,

What a change! Anyways, I am having a weird issue that I could not even see any info when the call is presented. I could only see the message 'Reserved for Calls'. And the 'answer' button is also missing. I guess it is related to browser, although I have tried both IE 11 and Firefox. Have you ever seen this?

See screenshot I have. Help is highly appreciated.



Yes, that's caused by a javascript error or a hung javascript function.

Web Browsers execute everything in a web page on a single thread.  This means that if you hit a javascript error and the browser stops processing javascript on the page, the UI will no longer update.  It also means that if your browser is running an abnoxiously large javascript function the browser UI will stop updating until it completes as well.

Could be that you are using a gadget that is causing the problem or your web browser config is causing it.  Best way to find out is the javascript console... Look for errors in there.


Thanks, Eric,

It is a new installation and I am not using any customized gadget so far. I have tried quite a few different browsers even from Windows XP, with the same result. I opened JavaScript console within the IE page, and could not see any error. Also I found when the call is connected, I start to see the call info and the 'end' button. 

I know a co-worker agent has her browser show correctly, so it is not server-end issue. Do you know any specific browser version I have to use to be compatible? I recall it says IE 11 is supported and recommended.