Overview
The main use of field codes is to particularize standard responses.
For example, you can use the field code <$Contact.FirstName$> in a response beginning "Dear <$Contact.FirstName$>", which you send to dozens of recipients. In each message, <$Contact.FirstName$> is replaced by the first name of the addressee of the message (the contact) as listed in the Universal Contact Server database.
More generally, a "field code" is a formula that you insert into an outgoing text object, such as an email that E-mail Server generates when triggered to do so by a routing strategy object.
The most common type of such a text object is a standard response (triggered by an Autoresponse or Acknowledgement object), but you can also insert field codes into other types, such as chat transcripts, SMS messages, and forwarded or redirected emails. In some cases, the only place you can insert a field code is in the Subject line using the Format tab in a strategy object.
The following is a complete list of the strategy objects that can use field codes either in a standard response or in the Subject line:
- Acknowledgement
- Autoresponse
- ChatTranscript
- Create EmailOut
- Create Notification
- Create SMS
- Forward
- RenderMessageContent
The following is a complete list of the strategy objects that can use field codes only in the Subject line:
- Redirect
- Reply from External Resource
- Send
When a text object containing such a formula is processed, the following happens:
- The formula performs an operation, which produces a result.
- The result replaces the field code in the text object.
This process of performing an operation and substituting its result is called "rendering."
Using Formulas in Field Codes
A complete reference list of field codes is available in the Genesys Field Codes Reference Information section.
In addition to system variables such as Contact.FirstName, field codes may contain formulas. This section provides an outline of formula usage. Details on many of these topics are provided in the Genesys Field Codes Reference Information section.
You must always delimit field codes by using <$ … $>. If you type a field code directly into the body of a standard response, then you must enter the delimiters yourself. If you select from the list of field codes, then the delimiters are added automatically.
The text that appears inside the delimiters is a formula. Field code formulas are very similar to formulas in other applications, such as Microsoft Excel.
A formula is a sequence of one or more operands (such as numbers and text strings), separated by operators (such as +
and -).
For example, in the following formula, 2 and 3 are operands and + is an operator:
-
<$2 + 3$>
Operands can be values that do not change (constants), or values that vary based on the context. In the previous formula, all the operands are constants, so the formula always evaluates to 5. The next formula, on the other hand, evaluates to a different value for each agent who uses it:
-
<$Agent.Signature$>
Field Code Syntax
To summarize field code syntax:
-
A field code must be delimited by <$ ... $>.
-
Alphabetic strings, whether constants in formulas or elsewhere in a field code, must be enclosed in double quotes.
-
Numeric constants require no special treatment.
- You must use special characters for some purposes. For example, for your field code to render with a line break, you cannot simply type a carriage return. Instead, you must insert the expression \n. A list of these special characters is available.
HTML in Field Codes
With special configuration, field codes can contain HTML markup; for example, you could have a field code <$my.agent.signature$> defined as
Sam Agent<BR /> Acme Products<BR /> 29 Exterior Blvd<BR /> Springfield, CX 09090<BR />
To enable this, you must use the Java property -Dsrl-field-code-allow-html=true, in one of the following ways:
- Add it to the JavaArgs section of ContactServerDriver.ini
- Add it as an argument to the startup command line in contactServer.sh.
Operator Precedence
If you use more than one operator in a formula, the order in which they are evaluated depends on their relative precedence (higher precedence operators are evaluated first). For example, multiplication (*) has a higher precedence than addition (+ ), so that the formula below evaluates to 14, not 20:
-
<$2 + 3 * 4$>
You can use parentheses to override the default precedence. The formula below evaluates to 20:
-
<$(2 + 3) * 4$>
For a complete list of operators and their relative precedence, see "Operator Precedence” in the Genesys Field Codes Reference Information section.
Data Types
Operands of several different types may appear in formulas:
-
Number
-
String (text)
-
Date/time
-
Boolean (true/false)
-
Object (Contact, Interaction, and Agent)
Each data type behaves differently in formulas, and the operators have different meanings when you use them with different data types. For example, the + operator means “add” when used with numbers, but “concatenate” (paste together) when used with strings. This formula evaluates to Uncle Sam Wants You
-
<$"Uncle Sam " + "Wants You"$>
In addition, some operators cannot be used with some data types at all. For example, you cannot use the multiplication (*
) operator on two strings.
All formulas, regardless of their final data type, are converted to strings before being merged into your standard response. This conversion follows a set of default rules that depend on the data type. For example, the default rules for numbers round them off to integers. This formula causes 2 to be inserted into your standard response, even though the real result is 2.25:
-
<$9 / 4$>
You can use the Text function (see below) or format operator:) to override the default formatting. Either of the following formulas inserts 2.25 into your standard response:
-
<$Text(9 / 4, "#.##")$>
-
<$(9 / 4):"#.##"$>
For a detailed list of data types and how you can use them, see "Data Types” in the Genesys Field Codes Reference Information section.
Functions
When composing formulas, you can use many built-in functions. Functions are predefined formulas that perform calculations using values, called arguments, which you supply. To use a function, write its name, followed by an opening parenthesis, the arguments for the function separated by commas, and a closing parenthesis.
Function arguments may be of any data type, although individual functions may place restrictions on their arguments. Function arguments may be constants or formulas. The Length function, for example, takes a single string argument and returns its length in characters. This formula evaluates to 13:
-
<$Length("Hello, world!")$>
As another example, the Date
function takes individual date components (year, month, day, and so on), and constructs a date/time value. The formula below evaluates to 1965-11-23 09:03:10:
-
<$Date(1965, 11, 23, 9, 3, 10)$>
Functions may act as arguments to other functions. The WeekdayName function takes a single date/time argument and returns the day of the week as a string. The formula below evaluates to Tuesday:
-
<$WeekdayName(Date(1965, 11, 23, 9, 3, 10))$>
This formula evaluates to 7:
-
<$Length(WeekdayName(Date(1965, 11, 23, 9, 3, 10))$>)
For detailed descriptions of all available functions, see "Functions” in the Genesys Field Codes Reference Information section.
<$ Agent.FirstName + Interaction.DateCreated $>This formula causes an error, as it mixes two data types: Text (Agent.FirstName) and Date (Interaction.DateCreated). Instead, use the Text type for both types, as shown below:
Agent.FirstName + Text(Interaction.DateCreated)Using Objects
All object/property pairs are also available in the Variables drop-down menu in the Field Code Editor.
Object properties can be of any data type. Agent.FullName, for example, is a string, but Interaction.DateCreated is a date/time.
The data type of an object property can even be another object. For example, Contact.EmailAddresses yields another object called a ContactEmailAddressList. In cases such as this, you can access the properties of the resulting object by entering a period (.), followed by the property name, just as before. For example, the formula below evaluates to the number of email addresses assigned to the contact:
-
<$Contact.EmailAddresses.Count$>
Some object properties require arguments just as functions do. For these properties, write the arguments, enclosed in parentheses after the property name, just as before.
For example, the ContactEmailAddressList object has a property named Exists, which you can use to test whether a particular email address is assigned to a contact. The data type of this property is Boolean (true/false), and it takes one argument, the email address to test. For example:
-
<$Contact.EmailAddresses.Exists("samd@acme.com")$>
For detailed descriptions of all objects and their properties, see "Objects” in the Genesys Field Codes Reference Information section.