Formulas (Release 4.6.2)

•

A discussion of variables you can use within formulas (Call Control, Expanded Call Context (ECC), and User variables)

•

Descriptions and examples for using operators, built-in functions, and custom functions in expressions

Introducing Formulas

A formula consists of one or more expressions that ICM software evaluates to produce a value which it can use for subsequent script processing. You define an expression, which is made up of variables, constants, operators, and functions, to set up custom selection rules or distribution criteria in scripts.

•

The Left-value or Right-value is a number, string, variable, function, or other expression.

•

The Operator is a symbol that compares the Left-value to the Right-value.

Variables are discussed in detail beginning on page 5-3 of this chapter; operators and functions beginning on 5-12.

Figure 5-2 shows a simple formula that evaluates the value of CallerEnteredDigit variable.

In Figure 5-2, if the CallerEnteredDigit value is equal to 1, the formula returns a value of true; if the CallerEnteredDigit value is not equal to 1, the formula returns a value of false.

The Formula Editor

Many Script Editor node fields require a formula. In some cases, you can simply key the formula into this field. In most cases, however, you will need to click an Edit Formula button to access the Script Editor's Formula Editor, shown in Figure 5-3.

•

Use the tab lists at the bottom of the Formula Editor dialog box to choose variables and functions and place them in the Formula field.

Introducing Variables

You use variables, which are named objects that can hold a value, in formulas to:

This section describes how to use variables in a formula and the different types of variables that are available.

To see all available categories and the specific variables in each category, see the Variables tab in the Formula Editor dialog box.

Note For information on a specific real-time variable, see the description of the appropriate table in the Cisco ICM Software Database Schema Handbook or the online ICM Schema Help.

How to Use Variables in a Formula

•

The object-name is the name of an object contained in the ICM database, for example, the name of a Service (for example, BosSales).

•

The variable-name is a named object that can hold a value, for example, a call control variable (for example, CallerEnteredDigits).

A Single-Target Variable

Figure 5-4 shows an example of a formula that examines the ExpectedDelay variable for a Service, BosSales.

A Multiple-Target Variable

To use a variable to examine multiple targets of a node, use an asterisk (*) as the object-name value. When ICM software executes a variable with an asterisk, it replaces the asterisk by each target in turn.

For example, you could include the formula in Figure 5-5 in a Select node to find the skill group with the maximum value of the variable LongestAvailable.

Call Control Variables

The call control variables provide information about the current call request. They include information about where the request came from, call classification data, and information to be passed to the peripheral that receives the call.

You can set the values with some call variables with the Set Variable node. To reference a call control variable in a script, the syntax is Call.variable.

Table 5-1 Call Control Variables
Variable	Data Type	Description	Settable
CallerEnteredDigits	String	Digits caller entered in response to prompts.	Yes
CallingLineID	String	Billing telephone number of the caller.	No
CLIDRestricted	Integer	If 1, CLID presentation should be restricted. If 0, CLID presentation should not be restricted.	No
CustomerProvidedDigits	String	Digits to be passed to the routing client for forwarding to the call recipient.	Yes
DialedNumberString	String	Telephone number dialed by the caller.	No
ExpCallVarName	String	Expanded Call Context (ECC) variable value assigned in scripts and passed with call.	Yes
NetworkTransferEnabled	Integer	If 1, network transfer is enabled. If 0, network transfer is not enabled.	Yes
PeripheralVariable1-PeripheralVariable10	String	Values passed to and from the peripheral.	Yes
RequeryStatus	Integer	Provides the ability to test the error path of the Label, Queue, RouteSelect, and Select script nodes to determine the specific network cause of failure and conditionally retry the attempt as necessary.	No
RouterCallDay	Integer	An encoded value that indicates the date on which ICM software processes the call.	No
RouterCallKey	Integer	A value that is unique among all calls ICM software has processed since midnight. RouterCallDay and RouterCallKey combine to form a unique call identifier.	No
RoutingClient	String	Name of the routing client that made the route request.	No
TimeInQueue	Integer	Number of seconds a call has been queued.	No
UserToUserInfo	String	ISDN private network User to User information.	Yes
VruStatus	Integer	Indicates the result of a previous VRU node.	Yes

Note For a Post-Routing� request from an Aspect ACD, PeripheralVariable1 through PeripheralVariable5 map to the Aspect variables A through E. The Aspect routing client passes these variables to ICM software as part of the request and ICM software returns them with the response. Other routing clients might use some of these variables for other purposes. The values of these variables are also stored in the Route_Call_Detail table of the ICM database.

Expanded Call Context (ECC) Variables

Expanded Call Context (ECC) variables are variables that you define and enable in the Configuration Manager to store values associated with the call. You can specify the variable name and data type. The name must begin with the string user. These are in addition to the variables the ICM software defines for each call (PeripheralVariable1 through PeripheralVariable10, CallerEnteredDigits, CallingLineID, etc.).

An ECC variable name can be up to 33 bytes long (1-32 usable characters + a null terminator). In addition, it is highly recommended that you use the following naming convention when creating an ECC variable:

For example, you could use the following name for an ECC variable created for Cisco account numbers:

Using this naming convention will prevent naming conflicts with any third-party applications that interface with ICM software.

Note If your corporation is large, you may even want to break <VariableDescription> down to include the Business Unit, Division, or other organizational entity that exists in your company.

The maximum buffer size for each scalar variable = 5 + the maximum length of the variable where the 5 bytes includes 4 bytes to tag the variable and 1 byte for the null terminator.

The maximum buffer size for each array = 5 + (1 + the maximum length of array element) * (the maximum number of elements in the array). There is a null terminator for each element, as well as a null terminator for the array as a whole.

Since the total size of the buffer used to store the variables internally is 2000 bytes, the total sum of all the maximum buffer sizes for each variable and each array must be no greater than 2000.

For example, if you intended to use one scalar ECC variable with a maximum length of 100 bytes, one scalar ECC variable with a maximum length of 80 bytes, and an ECC array with a maximum of 9 elements with each element having a maximum length of 200 bytes, the buffer size would be:

This is too large so the length of one of the scalar ECC variables or the length of the array ECC variable needs to be adjusted.

•

Setting the Enable Expanded Call Context option in the System Information dialog box

•

Defining the variable through the Expanded Call Variable List in the Configuration Manager

How to set the Enable Expanded Call Context option

Step 1

Within the Configuration Manager, select Tools > Miscellaneous Tools > System Information. The System Information window appears.

How to define an Expanded Call Context (ECC) variable

Step 1

Within the Configuration Manager, select Tools > List Tools > Expanded Call Variable List. The Expanded Call Variable List window appears.

Step 2

In the Expanded Call Variable List window, enable Add by clicking Retrieve.

Note The Name and Maximum Length fields are required. All other fields are optional. The Name must begin with "user" and cannot exceed 32 characters. The recommended syntax is: user.<CompanyName>.<VariableDescription>.
For additional information refer to the online Help.

User Variables

You can also create global user variables. For example, you could create a user variable called usertemp to serve as a temporary storage area for a string value used by an If node.

•

Be associated with an object type, for example, Service. (This enables ICM software to maintain an instance of that variable for each object of that type in the system.)

•

Be identified as a persistent (retains value across CallRouter restarts) or non-persistent (does not retain value across CallRouter restarts) variable.

After you have defined a variable, you can then use the Script Editor's Formula Editor to access the variable and reference it in expressions, just as you would with a "built-in" variable

How to define a user variable

Step 1

Within the Configuration Manager, select Tools > List Tools > User Variable List. The User Variable List window appears.

Step 2

In the User Variable List window, enable Add by clicking Retrieve.

Note The Variable name, Object type, and Data type fields are required. All other fields are optional. For additional information refer to the online Help.

Operators

ICM software supports a large number of operators. Some operators have one operand; others have more than one. This section contains tables describing the various operators supported by ICM. Most of the table entries include examples.

Prefix Operators

Table 5-2 Prefix Operators
Operator	Meaning	Comments / Examples
+	Positive	Numeric values are positive by default, so the positive operator (+) is optional. Example: 2 and +2 represent the same value.
-	Negative	The negative operator (-) changes the sign of a value. Example: 2 represents a positive value; -2 represents a negative value.
!	Logical negation	A logical expression is any expression that evaluates to true or false. The logical negation operator (!) changes the value of a logical expression. Note Numerically, a false value equates to 0 and a true value equates to a non-zero value. Example: If the current value of SkillGroup.Sales.Avail is 3, then SkillGroup.Sales.Avail > 0 is true (because 3 is greater than 0) and !(SkillGroup.Sales.Avail > 0) is false (because 3 is not greater than 0).
~	One's complement	Operates on a bit value, changing each 1 bit to a 0 and each 0 bit to a 1. Note This operator is rarely used.

Arithmetic Operators

Table 5-3 Arithmetic Operators
Operator	Meaning	Comments / Examples
*	Multiplication	Arithmetic operators perform the basic operations of addition, subtraction, multiplication, and division. You can use them in making calculations for a skill group, service, or route. Note Multiplication () and division (/) operators are evaluated before addition (+) and subtraction (-) operators. Example: •Service.Order.AgentsLoggedOn - Service.Order.AgentsAvailable* returns the number of agents who are logged on to the service but not currently available. •*2 + 3 4** evaluates to 14 because the multiplication is performed first.
/	Division
+	Addition
-	Subtraction

Equality Operators

Relational Operators

Logical Operators

Table 5-4 Equality Operators
Operator	Meaning	Comments / Examples
==	Equal To	Equality operators allow you to determine whether two values are equivalent or not. Note The Equal To operator can also be written as a single equal sign (=). Example: •Service.Sales.CallsQNow != 0 is true if any calls are currently queued for the service. •Service.Sales.AgentsLoggedOn == Service.Sales is true if all agents logged on to the service are currently available.
!=	Not Equal To

Table 5-5 Relational Operators
Operator	Meaning	Comments / Examples
>	Greater than	Relational operators allow you to perform a more sophisticated comparison than the equality operators. Example: •SkillGroup.Sales.Ready < SkillGroup.Sales.NotReady is true if most members of the skill group are in the Not Ready state. •SkillGroup.Sales.Ready >= SkillGroup.Sales.NotReady is true if at least as many agents are Ready as Not Ready.
<	Less than
>=	Greater than or equal to
<=	Less than or equal to

Logical operators, listed in Table 5-6, take two operands. Logical operators examine the values of different logical expressions.

Table 5-6 Logical Operators
Operator	Meaning	Comments / Examples
&&	And	The expression is true if both of the operands are true. If either operand is false, the overall expression is false. Example: The following is true if the skill group has at least one agent logged on, but no agents currently available: SkillGroup.Sales.LoggedOn > 0 && SkillGroup.Sales.Avail == 0
\|\|	Or	The expression is true if either or both of the operands is true. If both operands are false, then the overall expression is false. Example: The following expression is true if the skill group has at least five agents logged on or no agents are currently available: SkillGroup.Sales.LoggedOn > 5 \|\| SkillGroup.Sales.Avail == 0 However, the expression is false if less than five agents are logged on and there is an agent available (SkillGroup.Sales.Avail does not equal 0).

Note The equality (==) and relational (<) operators are evaluated before the logical operators (&& and ||). (For more information about the order of evaluation, see the "Operator Precedence" section.)

Bitwise Operators

Table 5-7 Bitwise Operators
Operator	Meaning	Comments / Examples
&	And	Use the bitwise operators to turn specific bits in a value on or off. Example: Service.Sales.AvgTalkTimeTo5 & ~63 turns off (that is, sets to 0) the six low-order bits of AvgTalkTimeTo5. (Note the use of the one's complement operator (~) with the constant) This is equivalent to rounding the value down to the next multiple of 64.)
\|	Inclusive Or	Inclusive Or and Exclusive Or differ in the way they handle the case where bits in both values are 1: •Inclusive Or evaluates the result as true and sets a 1 bit in the result. •Exclusive Or evaluates the result as false and sets a 0 bit in the result. (An Exclusive Or applies the rule "one or the other, but not both.")
^	Exclusive Or

Miscellaneous Operators

The miscellaneous operators, which don't fit in any of the preceding categories, are listed in Table 5-8.

Table 5-8 Miscellaneous Operators
Operator	Meaning	Comments / Examples
?	Conditional	The conditional operator (?) takes three operands. Its syntax is as follows: condition ? true-result : false-result ICM software evaluates the expression by first examining the logical expression condition and then doing the following: •If the result is true, then the overall expression evaluates to the value of the expression true-result. •If the result is false, then the overall expression evaluates to the expression false-result. Example: The following expression determines whether the number of agents available for skill group S1 is even or odd: (SkillGroup.S1.Avail & ~01) ? "even" : "odd" Note You can achieve the same result by using the If function. See the description of the If function in Table 5-12.
&	Concatenation	The concatenation operator (&) joins two strings end-to-end. Example: "abc" & "def" returns the value "abcdef".
,	Sequential	The sequential or comma operator (,) takes two operands, each of which is an expression. ICM software evaluates the left expression first and then the right expression. The value of the overall expression is the value of the right expression. The first expression typically affects the valuation of the second. Call.CallEnteredDigits = 99, Valid(Call.CallerEnteredDigits) ? 1 : 0
<<	Shift left	The shift left (<<) and shift right (>>) operators shift the bits within a value. The following example shifts the bits in Avail two places to the left. The two rightmost positions are filled with zeroes: Avail << 2 The following example shifts the bits in Avail two places to the right. In this case, the positions are filled with sign bits (0 if the original value is positive or zero; 1 if the original value is negative). Avail >> 2
>>	Shift right

Operator Precedence

To write expressions correctly, you must understand the order in which ICM software evaluates each operator. Table 5-9 lists the levels of operator priority.

Note The operators with priority 1 are evaluated first, then those with priority 2, and so on. The order of evaluation within each priority level can also be important. Prefix operators are evaluated from right-to-left in an expression. Assignment operators are also evaluated from right-to-left. In all other cases where operators have equal priority, they are evaluated left-to-right.

Table 5-9 Operator Precedence
Priority	Operator Type	Operators
1	Prefix (unary)	+ - ! ~
2	Multiplication and division	* /
3	Addition and subtraction	+ -
4	Shift right and shift left	>> <<
5	Relational	< > <= >=
6	Equality	== !=
7	Bitwise And	&
8	Bitwise exclusive Or	^
9	Bitwise inclusive Or	\|
10	And	&&
11	Or	\|\|
12	Conditional	?
13	Sequential	,

Built-in Functions

ICM software provides a number of built-in functions that you can use in formulas. These functions allow you to manipulate dates and times, perform several standard mathematical operations, and so forth.

Table 5-10 Date and Time Functions
Function	Data Type	Return Value / Examples
date [ ( date ) ]	Integer	Returns the current system date or the date portion of a given date-time value. The given date can be a floating point value (as returned by the now function), a string of the form mm/dd/yy, or three integers: yyyy, mm, dd. Example: •date (with no arguments) returns the current date. •date() = date(2001, 7, 15) tests whether the current date is July 15, 2001. Note It is recommended that you not use the slash (/) character in defining a date function because it is the division operator. For this reason, the function date(7/15/01) would not return the results you'd be looking for. You could enclose the argument within a string--date("7/15/01")--but the preferred format is: date(2001,7,15).
day [ ( date ) ]	Integer	Returns the day of month (1-31) for the current date or a given date. The given date must be an integer or a floating-point value, as returned by the date or now function. Example: day(now+1) = 1 tests whether tomorrow is the first of the month.
hour [ ( time ) ]	Integer	Returns the hour (0-23) of the current time or a given time. The given time must be a floating-point value, as returned by the now function. Example: hour() < 12 tests whether the current time is before noon.
minute [ ( time ) ]	Integer	Returns the minutes (0-59) of the current time or a given time. The given time must be a floating-point value as returned by the time function. Example: (minute() >= 15) && (minute() < 30) tests whether the current time is in the second fifteen-minute interval after an hour.
month [ ( date ) ]	Integer	Returns the month (1-12) of the current month or a given date. The given date must be a floating-point value, as returned by the date or now function. Example: month() = 6 tests whether the current month is June.
now	Float	Returns the current date and time, with the date represented as an integer and the time represented as a fraction. Note You can use the date or time functions without any arguments to return just the current date or time. This function is useful for comparing the current date and time to a specific point in time. Example: to test whether the current date and time is later than 10 p.m., December 24, 2001, use the expression now() > date(2001,12,24) + time(22,0).
second [ ( time ) ]	Integer	Returns the seconds (0-59) of the current time or a given time. The given time must be a floating-point value, as returned by the time function. Example: second() >= 50 tests whether the current time is within the last ten seconds of a minute.
time [ ( time ) ]	Float	Returns the current system time or the time portion of a date-time value. The given time can be a floating point value, a string of the form "hh:mm:ss", or two or three numeric values: hh, mm [, ss ]. Example: •time (with no arguments) returns the current time. •time() > time("14:00:00") tests whether the current time is after 2:00 PM.
weekday [ ( date ) ]	Integer	Returns the current day of week (Sunday=1, Monday=2, etc.) of the current date or given date. The given date must be an integer or floating-point value, as returned by the date or now function. Example: weekday() = 3 tests whether today is Tuesday.
year [ ( date ) ]	Integer	Returns the year of the current year or given date. The given date must be a floating-point value, as returned by the date or now function. Example: year() >= 2001 tests whether the millennium has passed.

Table 5-11 Mathematical Functions
Function	Data Type	Return Value
abs(n)	Numeric	Returns the absolute value of n (the number with no sign). Example: abs(-15) returns the value 15.
max(n1, n2 [ , n3 ] . . .)	Numeric	Returns the largest of the operands. Each operand must be numeric. Example: max(0, -2, 3) returns the value 3.
min(n1, n2 [ , n3 ] . . .)	Numeric	Returns the smallest of the operands. Each operand must be numeric. Example: min(0, -2, 3) returns the value -2.
mod(n1, n2)	Numeric	Returns the integer remainder of n1 divided by n2. Example: mod(1999, 100) returns the value 99.
random()	Numeric	Returns a random value between 0 and 1.
sqrt(n)	Numeric	Returns the square root of n. (The operand n must be numeric and non-negative.) Example: sqrt(49) returns the value 7.
trunc(n)	Numeric	Returns the value of n truncated to an integer. Example: trunc(28.35) returns the value 28.

Table 5-12 Miscellaneous Functions
Function	Data Type	Return Value
after(string1, string2)	String	That portion of string2 following the first occurrence of string1. If string1 does not occur in string2, the null string is returned. If string1 is the null string, string2 is returned. Example: after("bc", "abcdefg") returns the value "defg".
before(string1, string2)	String	That portion of string2 that precedes the first occurrence of string1. If string1 does not occur in string2, string2 is returned. If string1 is the null string, the null string is returned. Example: before("de", "abcdef") returns the value "abc".
ClidInRegion(string)	Logical	Indicates whether the CLID for the current call is in the geographical region specified by string. The value string must be the name of a defined region. You can use the Name variable of a region to avoid entering a literal value. Example: CLIDInRegion("Maryland") tests whether the CLID is from the Maryland region.
concatenate(string1, string2, ...)	String	Returns the concatenation of the arguments. The function takes up to eight arguments. Example: concatenate("ab", "cde") returns the value "abcde".
find(string1, string2 [ , index ])	Integer	Returns the starting location of string1 within string2. If you specify an index value, searching starts with the specified character of string2. Example: find("cd", "abcabcde") returns the value 6.
if(condition, true-value, false-value)	Logical	Returns a value of true-value if the condition is true; false-value if the condition is false. Example: if(hour()>12, hour()-12, hour()) returns the current hour in 12-hour format rather than 24-hour format.
left(string, n)	String	Returns leftmost n characters of string. Example: left("abcde", 3) returns the value "abc".
len(string)	Integer	Returns the number of characters in string. Example: len("six") returns the value 3.
mid(string, start, length)	String	Returns a substring of string beginning with the start character and continuing for length characters. Example: mid("abcde", 2, 3) returns the value "bcd".
result	Numeric	Returns the result of the current Select node. (This function is valid only in a Select node.) Example: If you are using the LAA rule in the Select node, result returns the number of seconds the selected agent has been available.
right(string, n)	String	Returns the rightmost n characters of string. Example: right("abcde", 3) returns the value "cde".
substr(string, start [ , length ] )	String	Returns a substring of string beginning with start character and continuing for length characters. Example: substr("01851-1234",1,5) returns the value 01851.
text(n)	String	Converts a numeric value to a string. Example: text(5) returns the value "5".
valid(variable)	Logical	Returns whether variable has a valid value. For example, valid(Database.C.Name) tests whether this is a valid value.
ValidValue(variable, value)	String	If variable has a valid value, returns that value; otherwise, returns value. Example: ValidValue(Database.C.Name, "None") returns either a name from the database or the string value "None".
value(string)	Numeric	Converts a string to a numeric value. Example: value("5") returns the value 5.

Custom Functions

You can create custom functions for use within scripts. A custom function represents an expression. Optionally, the expression can contain parameters that receive values when the function is called.

How to add a custom function

Step 1

Within Script Editor, select Script > Custom Functions. The Custom Functions dialog box appears, listing all the custom functions currently defined.

•

Number of Parameters. The number of parameters to be passed to the function. A function may take 0, 1, or more parameters.

•

Function definition. The expression to be evaluated when the function is called. When entering the function definition, keep the following in mind:

–

The parameters to a function are numbered beginning with 1. To reference a parameter within the expression, surround it with percent signs (%). For example, %3% is a reference to the third parameter.

–

The lower portion of the dialog box is just like the Formula Editor. You can use it to help build the expression.

Step 4

When done, click the Test button. The Test Function dialog box appears.

Step 5

Test the function by entering an example of how you might reference the function. Include a specific value for each parameter.

Step 6

Click the Evaluate button to see how the Script Editor interprets the function call and click Close to return to the Add Custom Function dialog box.

Step 7

Use one of the Validate buttons to validate the scripts that reference a selection function. (The Validate All button lets you validate all the scripts that reference any custom function.)

Step 8

When finished, click OK to apply changes and to close the dialog box.

How to import a custom function

Step 1

Within Script Editor, select Script > Custom Functions to open the Custom Functions dialog box.

Step 3

Choose a file name with an ICMF extension (.ICMF) and click Open. The Script Editor examines the file for naming conflicts. If a conflict is found, a dialog box appears listing options for resolving the conflict.

Note

If you choose to rename the function, the new name must begin with user.

•

If all imported objects were successfully auto-mapped, a message window appears prompting you to review the mappings. Click OK to access the Object Mapping dialog box.

•

If some imported objects were not successfully auto-mapped, the Object Mapping dialog box appears, with all unmapped objects labeled "Unmapped."

Step 6

(Optional.) Click an Imported Object value. The Mapped To column displays all the valid objects on the target system.

Step 7

(Optional.) Select an object from the Mapped To column's drop-down list on the target system that you want to map the imported object to.

Note

Multiple objects may be mapped to the same target. Objects may be left unmapped; however, the resulting custom function will not be valid until all objects are mapped.

How to export a custom function

Step 1

Within Script Editor, select Script > Custom Functions to open the Custom Functions dialog box.

Step 2

Select the custom function(s) from the list and click Export. The Export Custom Function dialog box appears.

Note

If you selected a single function, that function's name appears in the File Name field. If you selected more than one function, the File Name field is blank.

Note

You cannot change the file type; the script can only be saved in .ICMF format.

Step 4

Click Save. If the file name already exists, the system prompts you to confirm the save.

Step 5

If prompted, click OK. The custom function(s) are saved to the specified file in text format.

Table Of Contents

Formulas

Introducing Formulas

The Formula Editor

Introducing Variables

How to Use Variables in a Formula

A Single-Target Variable

A Multiple-Target Variable

Call Control Variables

Expanded Call Context (ECC) Variables

How to set the Enable Expanded Call Context option

How to define an Expanded Call Context (ECC) variable

User Variables

How to define a user variable

Operators

Prefix Operators

Arithmetic Operators

Equality Operators

Relational Operators

Logical Operators

Bitwise Operators

Miscellaneous Operators

Operator Precedence

Built-in Functions

Custom Functions

How to add a custom function

How to import a custom function

How to export a custom function