A global data variable is globally accessible and modifiable from all calls to all applications. Global data is given a single namespace within VXML Server that is shared across all calls to all applications. If a component changes global data, that change is immediately available to all calls for all applications. Global data can hold any data, including a Java object. The lifetime of global data is the lifetime of VXML Server. Global data is reset if the application server is restarted or the VXML Server web application archive (WAR) is restarted.

Global data typically is used to store static information that needs to be available to all components, no matter which application they reside in. For example, the holiday schedule of a company that applies to all applications for that company.

An application data variable is accessible and modifiable from all calls to a particular application. Application data variables from one application cannot be seen by components in another application. Each application is given its own namespace to store application data. If a component changes application data, that change is immediately available to all other calls to the application. Application data can hold any data, including a Java object. The lifetime of application data is the lifetime of the application. Application data would be reset if the application were updated and would be deleted if the application were released.

Application data is typically used to store application-specific information that does not change on a per call basis and is to be available to all calls (for example, the location of a database to use for the application).

Session data variables are accessible and modifiable from a single call session. Session data variables in one call cannot be accessed by components handling another call. Each session has its own session data namespace; session data set by one component will overwrite existing session data that has the same name. Session data can hold any data, including a Java data structure. The lifetime of session data is the lifetime of the session or the call. When the call ends, the session data is deleted.

Any component accessed within a call session, including elements, can create, modify, and delete session data. Session data can be created automatically by the system in two ways:

• If the voice browser passes additional arguments to VXML Server when the call is first received, these additional arguments will be added as session data with the arguments’ name or value pairs translated to the session data name and value (both as String types). For example, if the voice browser calls the URL:

  http://myserver.com/CVP/Server?audium_application=MyApp&SomeData=1234

  This session will create session data named SomeData with a value of 1234 in every call session of the application MyApp that starts through this URL.

• If a Unified CVP voice application performs an application transfer to another application and the developer has chosen to pass data from the source application to the destination application, then this data will appear as session data in the destination application (the data is renamed before it is passed to the destination application). Refer to the Call Studio documentation for more information on application transfers.

Element data variables are accessible from a single call session and modifiable from a single element within that call session. As the name suggests, element data can only be created by elements (excluding start and end of call events, the global error handler, hotevents, and XML decisions). Dynamic configurations are technically part of an element since they are responsible for configuring an element, so they can also create element data. Only the element that created an element data variable can modify or delete it, though it can be read by all other components. Due to the fact that the variable belongs to the element, the variable namespace is contained within the element, meaning two elements can define element data with the same name without interfering with each other. To uniquely identify an element data variable, both the name of the element and the name of the variable must be used. Like session data, the lifetime of session data is the lifetime of the session or the call. When the call ends, the element data is deleted.

The following table lists each component and its ability to get and set global, application, session, and element data.

Note	Hotevents, which are VoiceXML code appearing in the root document, do not have access to any server-side information.

Note	A Say It Smart plug-in’s purpose is to convert a value into a list of audio files, so it does not need to access server-side information.

Note	A Logger's only responsibility is to report or log data and has access to all variables types but cannot set them.

Note	On Error Notification classes are given the session data that existed at the time the error occurred.

The call_data Tag figure shows the term that represents information about the current call. The type attribute can be ani, dnis, uui, iidigits, source, appname, duration, language, or encoding. The ANI, DNIS, UUI, and IIDIGITS will be NA if it is not sent by the telephony provider. Source is the name of the application that transferred to this application or null if this application was the first to be called. Duration is the duration of the call up to this point in seconds.

The <data> Tag figure shows the term that represents session or element data. The <session> tag refers to session data with its name in the name attribute. The <element> tag refers to element data with the name of the element in the name attribute and the name of the variable in the variable attribute.

The <user_info Tag figure shows the term that represents user information.

Note	If the application has not been configured to use the user management system, and the call was not associated with a specific UID, using this term will cause an error.

Only one piece of user information can be returned per tag.

The possible user information to be compared is:

• demographic—This tag refers to the user’s demographic information. The type attribute can be name, zipcode, birthday, gender, ssn, country, language, custom1, custom2, custom3, or custom4.

• ani_info—This tag refers to the various phone numbers associated with the user account. If the type attribute is first, the first number in the list of numbers is returned. This is returned if there was only one number associated with an account. If the attribute is num_diff the total number of different phone numbers associated with the account is returned.

• um_diff

  user_date_time—This tag refers to date information related to the user account. The type attribute indicates which user-related date to access and the field attribute is used to choose which part of the date to return. Type can be last_modified (indicating the last time the account was modified), creation (indicating the time the account was created), and last_call (indicating the last time the user called). Field can be hour_of_day (which returns an integer from 0 to 23), minute (which returns an integer from 0 to 59), day_of_month (which returns an integer from 1 to 31), month (which returns an integer from 1 to 12), day_of_week (which returns an integer from 1 to 7 where 1 is Sunday), or year (which returns the 4 digit year).

• called_from_ani—This tag returns true if the caller has previously called from the current phone number, false if not.

• account_info—This tag refers to the user’s account information. The type attribute can be pin, account_number, or external_uid.

The general_date_time> Tag figure shows the term that represents general date information. The type attribute indicates which date to access and the field attribute is used to choose which part of the date to return. Type can be current (indicating the current date/time) or call_start (indicating the time the call began). Field can be hour_of_day (which returns an integer from 0 to 23), minute (which returns an integer from 0 to 59), day_of_month (which returns an integer from 1 to 31), month (which returns an integer from 1 to 12), day_of_week (which returns an integer from 1 to 7 where 1 is Sunday), or year (which returns the 4 digit year).

The <caller_activity> Tag figure shows the term that represents the activity of the caller in the current call. The <nth_element> tag returns the nth element visited by the caller where the attribute n is the number (starting at 1). The <nth_exit_state> tag returns the exit state of the nth element visited by the caller where the attribute n is the number (starting at 1). The <times_elemvis> tag returns the number of times the caller visited the element whose name is given in the element attribute. The <times_elemvis_exit> tag returns the number of times the caller visited the element whose name is given in the attribute element, which returned an exit state whose name is given in the exit_state attribute.

The <historical_data> Tag figure shows the term that represents the historical activity of the user associated with the call on the current application.

Note	If the application has not been configured with a user management database, using this term will cause an error.

The type attribute determines what kind of value is returned. A value of num means that the value returned is the number of calls matching the criteria defined by the children tags. A value of last_date_time means that the value returned is the last date/time a call was received matching the criteria defined by the children tags. A value of first_date_time returns the first date/time a call was received that matched the criteria.

The field attribute is used if the type attribute is first_date_time or last_date_time and indicates which part of the date to compare. Field can be hour_of_day (which returns an integer from 0 to 23), minute (which returns an integer from 0 to 59), day_of_month (which returns an integer from 1 to 31), month (which returns an integer from 1 to 12), day_of_week (which returns an integer from 1 to 7 where 1 is Sunday), or year (which returns the 4 digit year). The children tags are used to turn on various criteria to add to the search.

The different search criteria are:

• caller—If this tag appears, the search looks for calls made by the current caller only. If it does not appear, it will search all calls made by all callers.

  Note	If the call was not associated with a specific UID, an error will occur if this tag is used.

• ani—If this tag appears, the search looks for calls made by the ANI specified in the value attribute. If the value attribute is not included, the ANI of the current caller is used.

• start—If this tag appears, the search looks for calls whose start date/time are between two times specified by successive <constant_date_time> children tags. The attributes of <constant_date_time> define the specific date to use. The month attribute must be an integer from 1 to 12. The day_of_month attribute must be an integer from 1 to 31. The year attribute must be a four digit integer. The hour_of_day attribute must be an integer from 0 to 23. The minute attribute must be an integer from 0 to 59. The second attribute must be an integer from 0 to 59.

• end—If this tag appears, the search looks for calls whose end date/time are between two times specified by successive <constant_date_time> children tags. See <start> (the previous bullet) for the description of the <constant_date_time> tag.

• flag—If this tag appears, the search looks for calls where a flag with the name given in the name attribute was triggered.

The following restrictions apply to a VoiceXML insert element. An insert element conforming to these restrictions will be assured full integration with the Unified CVP application. These restrictions will be clarified later.

• The insert element cannot define its own root document, a root document generated by VXML Server must be used.

• The variables to return to VXML Server, including the exit state, must conform to a strict naming convention.

• When using the <return> tag, Unified CVP-specified arguments must be returned along with the custom variables.

Note	Use a VoiceXML insert element only in a top-level subdialog. You cannot use a VoiceXML Insert element in a nested subdialog.

As with any element in the application, an insert element needs to be able to access information about the call such as element and session data, call data (such as the ANI), and even information found in the user management database if the application is configured to use one. Generally, this information is available in the Java or XML API. Because an insert element is written in VoiceXML, this information must be made available for the insert element to use from within the VoiceXML.

Unified CVP achieves this by creating VoiceXML variables in the root document containing all the desired information. The variable names conform to a naming convention so that the Insert element developer can refer to them appropriately. This is one reason why Unified CVP requires the use of the VXML Server-generated root document.

In order to reduce the number of variables appearing in the root document, the application designer is given the option of choosing which input groups are passed to the insert element. Additionally, the designer can individually choose which element and session data to pass. By minimizing the inputs to only the data required by the insert element, the overhead involved in using an Insert element is minimized.

These are the input types:

• Telephony—This information deals with telephony data. The inputs start with audium_telephony_.

  • audium_telephony_ani—The phone number of the caller or NA if not sent.

  • audium_telephony_dnis—The DNIS or NA if not sent.

  • audium_telephony_iidigits—The IIDIGITS or NA if not sent.

  • audium_telephony_uui—The UUI or NA if not sent.

  • audium_telephony_area_code—The area code of the caller’s phone number. Will not appear if the ANI is NA.

  • audium_telephony_exchange—The exchange. Will not appear if the ANI is NA.

• Call—This information deals with the call. The inputs start with audium_call_.

  • audium_call_session_id—The session ID.

  • audium_call_source—The name of the application which transferred to this one. Will not appear if this application is the first application in the call.

  • audium_call_start—The start time of the call in the format "DAY MNAME MONTH HH:MM:SS ZONE YEAR" where DAY is the abbreviated day of the week (for example, Wed), MNAME is the abbreviated name of the month (for example, Jun), HH is the hour (in military time), MM is the minute, SS is the seconds, ZONE is the time zone (for example, EDT), and YEAR is the four-digit year.

  • audium_call_application—The name of the current application.

• History—This information provides the history of elements visited so far in the call. The inputs start with audium_history_.

  • audium_history—This entire content of the element history (including exit states) is contained in this variable. The format is [ELEMENT]:[EXITSTATE]|..|[ ELEMENT]:[EXITSTATE] where ELEMENT is the name of the element and EXITSTATE is the name of the exit state of this element. The order of the element/exit state pairs is consistent with the order in which they were visited. This will not appear if this insert element is the first element in the call.

• Data—This is the element and session data created so far in the call.

  • audium_[ELEMENT]_[VARNAME]—The element variable where ELEMENT is the name of the element and VARNAME is the name of the variable.

    Note

    Both the element and variable names will have all spaces replaced with underscores. There may be no instances of this input if no element variables exist when this insert element is visited. For example, the variable audium_MyElement_the_value is element data named he value from the element MyElement.

  • audium_session_[VARNAME]—This is a session variable whose name is VARNAME.

    Note	The variable name will have all spaces replaced with underscores. The value is expressed as a string even if the type is not a string (the toString() method of the Java class is called). There may be no instances of this input if no session variables exist when this insert element is visited.

• User Data—This element information associated with the caller. It will only appear if the application has associated the call with a UID and a user management database has been set up for this application. The data will appear in the input exactly as in the database. The inputs start with user_.

  • user_uid—The UID of the user.

  • user_account_number—The account number of the user.

  • user_account_pin—The PIN of the user.

  • user_demographics_name—The name of the user.

  • user_demographics_birthday—The birthday of the user.

  • user_demographics_zip_code—The zip code of the user.

  • user_demographics_gender—The gender of the user.

  • user_demographics_social_security—The social security number of the user.

  • user_demographics_country—The country of the user.

  • user_demographics_language—The language of the user.

  • user_demographics_custom1—The value of the first custom column.

  • user_demographics_custom2—The value of the second custom column.

  • user_demographics_custom3—The value of the third custom column.

  • user_demographics_custom4—The value of the fourth custom column.

  • user_account_external_uid—The external UID of the user.

  • user_account_created—The date the account was created in the format. The value is in the format "DAY MNAME MONTH HH:MM:SS ZONE YEAR".

  • user_account_modified—The date the last time the account was modified. The value is in the format "DAY MNAME MONTH HH:MM:SS ZONE YEAR".

• User By ANI—Historical information about the phone number of the caller with regards to this application. It will only appear if a user management database has been set up for this application. The inputs start with user_by_ani_.

  • user_by_ani_num_calls—The number of calls made by this phone number.

  • user_by_ani_last_call—The last call made by the phone number. Will not appear if there were no calls made by this phone number in the past.

As with any element, VoiceXML insert elements can create element and session data, set the UID of the user to associate with the call, send custom logging events, and can return one of a set of exit states. As with voice elements, insert elements can have internal logging of caller activity and have global hotlinks and hotevents activated while the caller is visiting the Insert element. All of these actions involve variable data set within the Insert element and returned to VXML Server. These are crucial in order to properly integrate with the rest of the elements in the application.

These are the return arguments:

• audium_exit_state - The exit state of this VoiceXML insert element. The value of this variable must be exactly as chosen in the Builder for Call Studio when defining the insert element.

• element_log_[VARNAME] / element_nolog_[VARNAME] - These create new element data for this VoiceXML insert element whose name is VARNAME and which either sends a logging event to log the element data value or not, respectively. The data type will be assumed to be a string. The variable name cannot include spaces.

• session_[VARNAME] - This creates a new session variable whose name is VARNAME. The data type is assumed to be a string. The variable name cannot include spaces. If the variable name already exists, the old value will be replaced with this one. If the old data type was not a string, the new data type will be a string.

• custom_[NAME] - This sends a custom logging event whose contents is the action named NAME and the value of the variable being the description.

• set_uid - This associates the UID passed to the call.

• audium_hotlink, audium_hotevent, audium_error, audium_action - These four Unified CVP variables are created in the root document and must be passed along in the return namelist. The content of each deals with the occurrence of any global hotlinks, hotevents, errors, or actions (for example, a hang-up) while in this insert element. Because the subdialog has its own context and root document, this data has to be explicitly passed for any of these events to be recognized by VXML Server. The developer should not alter the contents of these variables.

• audium_vxmlLog - This variable contains the raw content for an interaction logging event. Adding to the interaction log is not required; the audium_vxmlLog variable can be passed empty. In order for VXML Server to parse the interaction data correctly, a special format is required for the content of the audium_vxmlLog variable.

  The format for interaction logging is:

  |||ACTION$$$VALUE^^^ELAPSED

  Where: ACTION is the name of the action.

  The following bullets list the possible action names and the corresponding contents of VALUE:

  • audio_group - Indicates that the caller heard an audio group play. VALUE is the name of the audio group.

  • inputmode - Reports how the caller entered their data, whether by voice or by DTMF key presses. VALUE should be contents of the inputmode VoiceXML shadow variable.

  • utterance - Reports the utterance as recorded by the speech recognition engine. VALUE should be the contents of the utterance VoiceXML shadow variable.

  • interpretation - Reports the interpretation as recorded by the speech recognition engine. VALUE should be the contents of the interpretation VoiceXML shadow variable.

  • confidence - Reports the confidence as recorded by the speech recognition engine. VALUE should be the contents of the confidence VoiceXML shadow variable.

  • nomatch - Indicates the caller entered the wrong information, incurring a nomatch event. VALUE should be the count of the nomatch event.

  • noinput - Indicates the caller entered nothing, incurring a noinput event. VALUE should be the count of the noinput event.

• ELAPSED is the number of milliseconds since the VoiceXML page was entered. The root document provides a JavaScript function named application.getElapsedTime(START_TIME) which returns the number of milliseconds elapsed since the time specified in START_TIME.

The root document created by VXML Server for use in all VoiceXML insert elements contains a VoiceXML variable named audium_element_start_time_millisecs that must be initialized with the time in order for the elapsed time intervals to be calculated correctly. This variable need only be initialized once in the first VoiceXML page of the insert element. All subsequent pages in the VoiceXML insert element must not initialize the variable because VXML Server requires the elapsed time from the start of the element, not the page. In VoiceXML, the line to appear must look like:

<assign name="audium_element_start_time_millisecs" expr="new Date().getTime()" />

For best results, this line should appear as early as possible in the first page, preferably in a <block> in the first <form> of the page, certainly before any additional logging is done.

In VoiceXML, setting the value of an existing variable requires the <assign> tag. Because the expression contains a JavaScript function, the expr attribute must be used. Additionally, in order to avoid overwriting previous log information, the expression must append the new data to the existing content of the variable. For example, to add to the interaction log the fact that the xyz audio group was played, the VoiceXML line would look like:

<assign name="audium_vxmlLog" expr="audium_vxmlLog + '|||audio_group$$$xyz^^^' +application.getElapsedTime(audium_element_start_time_millisecs)"/>

In another example, the utterance of a field named xyz is to be appended to the log. The VoiceXML would look like:

<assign name="audium_vxmlLog" expr="audium_vxmlLog +'|||utterance$$$'+ xyz.$utterance + '^^^' + application.getElapsedTime(audium_element_start_time_millisecs)"/>

The subdialog context written by the developer must refer to a Unified CVP-generated root document. This is essential for proper integration of the VoiceXML insert element with VXML Server. The root document call must look like:

"/CVP/Server?audium_vxml_root=true&calling_into=APP&
namelist=element_log_value|RTRN1|RTRN2|…"

Where APP is the application name and RTRNX represents the names of all the element data, session data, and custom log entries (delimited by ‘|’ characters) the insert element returns, using the same naming convention described in the outputs section.

The purpose for this requirement is related to how events are handled within the root document. The Unified CVP-generated root document catches events such as the activation of a global hotlink or a hangup, which then requires the call flow to leave the insert element. The insert element, however, may have created element and session data or added custom content to the log. This information is stored in VoiceXML variables that would be deleted once the subdialog context is exited. The root document needs to know which VoiceXML variables to send along to VXML Server when one of these events is triggered so that it can store them accordingly. In order to avoid problems that might occur if a global hotlink or hotevent was activated right after the insert element began, the variables to be returned should be declared as near the start of the VoiceXML insert element as possible, even if they are not assigned initial values.

Note	The ability to use a standard ampersand in the root document URL instead of escaping it (as &) is voice browser dependent. Most browsers will accept the escaped version so try that version first.

Note	If the insert element does not need to send back any data in the namelist parameter, only the element_log_value variable need be included (the parameter should look like this: "...namelist=element_log_value").