User Data

Transaction-related user data is structured as a list of data items described as key-value pairs, where the key stands for a parameter name and the value represents the current value of that parameter. Each key-value pair may contain information about only one parameter, whose value can be an integer, character string, binary type, or unicode.

Warning

Support for unicode is not backward compatible. Unicode should only be used in uniform 7.0 environments (where all clients use the 7.0 release of T-Library). In mixed environments, clients built with earlier releases of T-Library will not be able to decode unicode sent from 7.0 clients and servers.

There is no specific size limitation for the number of key-value pairs or for the size of individual keys or values. However, the total size of the key-value pairs is limited. When in a packed format, the total size of the pairs must not exceed the configured value (default is 16,000 bytes); the configured value has a maximum of 65,535 bytes.

Important

Increasing the configured value above 16,000 bytes, a feature introduced with release 7.0, may degrade performance. Moreover, if the value is set above the 16,000-byte default, release 6.5 components of a Genesys environment cannot properly process the data passed to them, and may even become unstable.

Arrival, Use, and Manipulation of User Data

User Data can arrive at a client application with any event that contains the UserData attribute in its TEvent structure. Client applications should be designed with the ability to view that data. Moreover, since applications may need to create or modify user data and send it to T-Server for processing elsewhere in the system, Genesys provides built-in functions for this purpose.

There are a variety of functions available for the creation and manipulation of user data. (See the Voice Platform SDK API Reference .NET or Java for details on all such available functions.) While these functions do not generate requests of T-Server, they allow client applications to create contact-related data structures understandable for other T-Server clients and to read and modify contact-related information coming from other clients via T-Server. A created or modified data structure will typically be sent to T-Server using the TAttachUserData() or TUpdateUserData() function (both of which are specified in the tlibrary.h header file). Examples of how to use user data functions are also available with the SDK documentation.

The functions for the creation and manipulation of user data fall into three broad groups: reading functions, creation functions, and modification functions. Reading functions are invoked every time an application wants to use contact-related information for its internal purposes. Creation and modification functions are only used by an application to make new data available to other client applications of T-Server.

User Data in Consultation Calls

In addition to creating and modifying user data, it is also important to provide ways for user data to be shared among parties on a consultation call. T-Server provides three methods of handling user data for consultation calls. In the first method, called the separate method, user data for the consultation call is attached and stored separately from the user data attached to the original call. In the second, called the inherited method, user data attached to the original call is copied to the consultation call at the moment the consultation call is initiated; after that, any changes to the original call's user data do not affect the consultation call's user data, and vice versa. In the third, called thejoint method, user data attached to either the original or the consultation call is associated with the original call and, yet, can be seen and changed by the parties of both calls.

A consultation call can be initiated with a T-Library request, such as TInitiateConference(), TInitiateTransfer(), or TMuteTransfer(). Use the Extensions attribute with the ConsultUserData key specified in the request to set the method of handling user data for a consultation call. Extensions for details on this attribute in other contexts. A key-value pair with the ConsultUserData key can have the following values:

• default
• separate
• inherited
• joint

Default Value

Applying the value default to the ConsultUserData key causes T-Server to use the current value specified for its consult-user-data configuration option. See your specific T-Server Deployment Guide to learn more about this option. If a conference/transfer request does not contain the ConsultUserData key, the value specified in the consult-user-data option applies. Otherwise, the method of handling user data is based on the value of the ConsultUserData key-value pair of the request.

Separate Method

Assigning the value separate to the ConsultUserData key tells T-Server to store an original call's user data separately from the consultation call's user data. Consequently, the data attached to the original call is only available to the original call's parties for review and change, while the data attached to the consultation call is only available to the consultation call's parties.

Inherited Method

Using the inherited value for the ConsultUserData key tells T-Server to copy the user data from the original call to the user data structure of the consultation call when the consultation call is initiated. After the consultation call is established, its user data is stored separately from the original call's user data. Further changes to the original call's user data are not available to the consultation call's parties and vice versa.

Joint Method

Using the joint value for the ConsultUserData key tells T-Server to maintain the same user data structure for the original call and for any number of derived consultation calls. The user data structure is associated with the original call, but any of the parties of the original and consultation calls can see and make changes in the common user data. T-Server associates the user data structure with the first consultation call in a consultation call chain when the original call has ended. (A consultation call chain is created when a consulted party initiates another consultation call.) If two consultation call chains are created on different legs of the ended original call, T-Server duplicates the user data structure and associates the structures with the chains independently. Further changes of user data made by the parties of one chain will not be visible to the parties of other chains.

User Data in Multi-Site Consultation Calls

For multi-site (ISCC) consultation calls, in addition to the ConsultUserData key or the consult-user-data option, setting the use-data-from T-Server common option also affects user data. The use-data-from option specifies for a given consultation call that is routed or transferred to a remote location, what the source of its values for the UserData and ConnID attributes should be. (For the full description, see the "Multi-Site Support Section" of the "T-Server Common Configuration Options" chapter of the T-Server Deployment Guide.)

The following call flow example illustrates how setting these different values affects the availability of user data.

Example

An established call for DN A on site A has a UserData attribute with the key M.

1. DN A on site A initiates a conference with DN B on site B. This call has additional UserData with the key C.
2. DN A on site A completes the conference.

Events on DN B have the following UserData according to how you set options consult-user-data and use-data-from.

Resulting Keys for User Data Based on Use of Different Options

Value of use-data-from	Value of consult-user-data
	separate	inherited	joint
original	M	M	M; C
active	C	M; C	M; C
current (1) a	C	M; C	M; C
current (2) b	M	M	M; C

a. If UserData is reported after the initiation of the conference, these keys result.
b. If UserData is reported after the completion of the conference, these keys result. The assumption for this case is that the option merged-user-data is set to main-only (the default value).