Text

Overview

The Text object refers to text files that can be played back or presented through an Output object. It is possible to refer to a single file only, to a specific entry within a file containing multiple text entries, or to a set of files that hold variations of a prompt (for more information on randomizing, see Output).
As examples:

File	Content
welcome.txt	Welcome to the Prime Telecom self-service portal.
selfService.properties	welcome=Welcome to the Prime Telecom self-service portal. mainMenu=Here is the list of choices topup=Top up your pre-paid minutes support=Get help from our support team

File

Content

welcome.txt

Welcome to the Prime Telecom self-service portal.

selfService.properties

welcome=Welcome to the Prime Telecom self-service portal.

mainMenu=Here is the list of choices

topup=Top up your pre-paid minutes

support=Get help from our support team

In addition, a text generation engine can be referred to through a Text object, in order to embed dynamically generated text into an application.
Alternative text can be provided, which is used if the text files are not available.

While the Text object is provided primarily as a means of managing prompts within text-based applications using the text or Web channel, it can equally be used to play Text-To-Speech prompts in the voice or video channel.

The Object Definition below covers the configuration of the Text object with VoiceObjects Desktop. For information on how to define this object type using VoiceObjectsXML refer to the VoiceObjectsXML Definition paragraph.

For information on how to manage the prompts of your application, refer to the Storyboard Manager Guide.

The Text object belongs to the object category Resources.

Dialog Flow Scenario

The following dialog flow example demonstrates an Output object with two Text objects.

Object		Dialog Flow
		Hello and welcome.
		This is your mobile self-service portal.

Object Definition

The Definition of the Text object provides the following sections:

· Text Resource
To specify an external text file.

· Parameter Set
To specify an optional set of parameters to be passed to text generation engines.

· Alternative Texts
To specify the alternative text that is used if the text file is not available.

For further details regarding additional object configuration refer to Precondition and Properties in this Object Reference.

Text Resource

The Text Resource section provides the following properties:

Property

Description

Location

Optional parameter to specify the location (using a Resource Locator object) of the file to be used.

File

Defines the file name of the file to be used. The name of the file can either be typed in or selected through a file browser by clicking the Browse button to the right of the File field. The filename can also be provided dynamically during call time by assigning a Variable, Expression, Script, or Layer object.

In Desktop for Web the Browse button will only be displayed if the Resource Locator object is available and includes a physical path definition.

File prefix

Optionally specifies a prefix that is applied to the file name. The file prefix can also be provided dynamically during call time by assigning a Variable, Expression, Script, or Layer object.

File suffix

Optionally specifies a suffix that is applied to the file name. The file suffix can also be provided dynamically during call time by assigning a Variable, Expression, Script, or Layer object.

Random variations

Defines whether randomizing is enabled for the text file. To enable randomizing set the Random variations property to a number between 2 or 99, by selecting an appropriate value from the drop-down list. If randomizing is enabled and different text files are provided with the specified file name extended by different numbers (e.g. welcome1.txt, welcome2.txt, welcome3.txt), the server will randomly pick one of the available files with a random file extension between 1 and the selected number whenever the Text object is processed. True randomizing ensures that all available text files are played before a repetition occurs.
By default, the Random variations property is set to Disabled indicating that no randomization is used.
For more information on randomization see the Output object.

Extension

Specifies the text file extension. Instead of selecting one of the provided file extensions from the drop-down list, the extension can also be supplied by using a Variable, Expression, Script, or Layer object.

The complete filename for the text file is generated at call time according to the following formula:

[prefix] + file + [suffix] + [random number] + [extension]

When using property-style references of the form file#key (see description below), the file name is generated as

[prefix] + file + [suffix] + [extension]

and the property name is generated as:

property + [random number]

When the Text Resource section refers to a single text file using the Location and File properties, e.g. WelcomeCaller, the complete content of this file is used. When reading the text file, the encoding specified for VoiceObjects Server is used so that, when configured appropriately, the text file may contain UTF-8 characters.

Alternatively it is possible to refer to an entry within a file containing multiple different texts. This file must then have a key/value pair structure based on Java properties files, e.g.:

welcome=Hello and welcome to Prime Telecom Self-Service.

goodbye=Thank you for calling Prime Telecom. Have a nice day.

To access a specific key within a file, the notation textFile#key is used.
Note that when using this notation, the actual file name and property name are generated according to the formula described above in Extension.

VoiceObjects Server caches the content of text files for best performance. The Tuning property Resource Fetching – Text Max Age can be used to configure the amount of time (in seconds) that an entry remains active within the cache. When this time expires, the file is loaded again the next time the Text object is processed. When using a file containing multiple text entries in a key/value structure, the entire file is cached or reloaded as necessary.

Parameter Set

The Parameter Set section is optional and relevant only for Text objects that refer to external text generation engines. Use it to define any number of parameters, all of which will be added to the final URL as CGI parameters, in order to control the engine if required.

The Parameter Set section provides the following properties:

Property	Description
Parameter	Specifies the value of the parameter. Possible parameter types are Variable, Collection, Expression, Layer, Resource Locator or Script objects, and constants. When using a Resource Locator object as a parameter, its URL definition is passed to the script. The field can be left empty to denote an empty value.
Alias	Optionally specifies the name of the parameter. If left empty, the reference ID of the object defined in the Parameter field will be used as the name. This means in particular that for constant values an alias needs to be defined (as they do not have a reference ID). Constant parameters without a defined alias are ignored.

The parameters will be added to the final URL in a CGI-string like fashion.

Alternative Texts

The Alternative Texts section optionally defines the text that is used when the text file is not defined or cannot be loaded.

The Alternative Texts section contains items to define the various texts for prompt variations, in case the Text object represents more than one file. The text entered into the Text field must not contain special characters such as quotation marks, apostrophes, ampersands etc. Also avoid using angle brackets unless you want to include SSML tags into your text. The alternative text can be typed in or can be set at call time by a Variable, Expression, Script, or Layer object.

In addition to the Text field, the following properties can be configured:

Property	Description
Label	Optional parameter to identify the alternative text item in a list.
Language	Text objects can represent prompts in multiple languages through dynamic resource locators. The Language drop-down list allows you to specify a language for a prompt, so that prompts of different languages can be incorporated into the Text object. When dealing with monolingual applications, this field can be ignored.
Layer	Associates the alternative text item with a custom layer. This item is only eligible for playback if the layer evaluates to true at call time. If you reference Text objects in different Output object items using different layer conditions, there is no need to also define the same layers in the Text object itself. If, on the other hand, different outputs are achieved by using a Layer (or Variable, Expression, Script) object within the resource locator definition of the Text object, you can define different alternative texts by associating items with the corresponding layer condition.
Variation	If randomizing is enabled, this field allows you to associate a text with a specific prompt variation number. If the Text object only refers to a single file, this can be left at the default value. Do not define multiple alternative text items with the same variation number (and the other settings being identical), as this may lead to unexpected behavior at call time. If you want to use the same alternative text for all randomized text files, you only need to define an alternative text for variation number 1.
Input mode	Associates the alternative text item with a specific input mode. Leave this property at the default value if your application does not distinguish between voice and DTMF input in the wording of your application prompts. Otherwise, tag the item with the appropriate mode.

SSML

The Speech Synthesis Markup Language (SSML), developed by the W3C Voice Browser Working Group, allows adding meta information to text that is supposed to be read out through a speech synthesis system. By using SSML, you have better control over how the TTS engine synthesizes speech. It allows you to define voice-related parameters like volume, speed, pitch, emphasis, pronunciation, etc. For more information on SSML, refer to the specification at the W3C website, or to chapter 4.1.1 of the VoiceXML 2.0 specification.

SSML markup can be included in any alternative text item, as well as in Output items. The server passes the extra code to the media platform without changes. The following example shows how to use SSML to tell the TTS engine to put emphasis on a specific word within a given prompt:

8 Caution: Since the markup you enclose in the alternative text item definition is passed to the platform as it is, make sure to provide the correct syntax required by SSML. Note that it is up to the platform or TTS engine, respectively, if and how SSML is interpreted. If a TTS engine does not support SSML, it might decide to read the XML tags out aloud.

VoiceObjectsXML Definition

The Text object is represented by the VoiceObjectsXML element <text>. It has six attributes and two groups of children.

In addition, the element has the standard attributes described in the XDK Guide.

The <text> element uses the embedded <altText> element.

Text

Attributes

· location
Defines the location from where the text file is to be retrieved. Must be a reference to a Resource Locator object.

· file
The file name of the text file, without extension. Can be a constant name, or a reference to a Variable, Expression, or Script object.

· prefix
A prefix to be used together with the text file name.

· suffix
A suffix to be used together with the text file name.

· random
Indicates whether randomization should be used. Can be either disabled or an integer >= 2 specifying the number of versions in which the file is available. If not specified, defaults to disabled.
For further information on randomization see Random Variations above.

· textFileExtension
Specifies the file extension for the text file as either a constant value or a reference to a Variable, Expression, or Script object. Legal constant values are none, txt, properties. If not specified, defaults to txt.

The complete filename for the text file is generated at call time according to the following formula:

[prefix] + file + [suffix] + [random number] + [extension]

Children

· <expression usage=”precondition”> or
<variable usage=”precondition”> or
<collection usage=”precondition”> or
<script usage=”precondition”>
Defines the precondition for the Text object.

· ?<parameterSet>
Defines the parameter set.

· *<altText>
Defines the corresponding alternative text(s).

Example

ParameterSet

Children

· +<item>
Defines the list of entries in the parameter set. The use of the alias attribute is optional when the object attribute is used, and required when the value attribute is used.

Example

</parameterSet>

Item

Attributes

· object
Defines a reference to an object. If this attribute is defined, the value attribute must not be defined.

· value
Defines a constant value. If this attribute is defined, the object attribute must not be defined.

· alias
Defines the parameter alias.

Example

AltText

The <altText> element defines the alternative texts to be used for the Text object. It may only occur embedded inside a <text> element.

The <altText> element has six attributes and contains text as a child.

Attributes

· label
A text string providing a name for the alternative text.

· random
Defines the random index to which this alternative text belongs. An integer >= 1. If not specified, defaults to 1.

· language
Defines the language for which this alternative text is valid. Can be default or a valid language code (e.g. de-DE, en-US, etc.). If not specified, defaults to default.
Appendix A – Language Codes contains a list of all language codes available in VoiceObjects together with the respective language they represent.

· inputMode
Defines the input mode for which this alternative text is valid. Can be default, voice, dtmf, or voicedtmf. If not specified, defaults to default.

· layer
Defines the layer for the alternative text. Can either be a reference to a Collection, Expression, Script, or Variable object; or a layer state reference of the form “Layer=State” or “Layer!=State” where “State” is the label of a state for the layer “Layer”.

· object
Optional reference to an Expression, Variable, or Script object that defines the alternative text.

Children

· CDATA
The static alternative text itself. Note that the text may not contain special characters such as apostrophes, quotation marks, etc. It may, however, contain XML markup to be used e.g. in combination with SSML.

Example

Bitte geben Sie Ihre Telefonnummer ein.

</altText>

<altText random=”1”> Sorry? </altText>

<altText random=”2”> Once more, please. </altText>

<altText random=”3”> I didn’t quite get that. </altText>

Object Interoperability

The following table contains all object types that can reference a Text object:

Icon	Object Name	Use Case Example
	Output	A Text object can be referenced within an Output object definition. In addition, a Text object can be referenced in all objects that provide Output items.
	List	A Text object can be referenced within the content formatting definition of a List object, to play back as part of the list content.
	OSDM	A Text object can be linked in the parameter set within any OSDM object.

Object Naming Conventions

In order to leverage the capabilities of the integrated documentation of VoiceObjects it is important to provide intuitive and self-explanatory object names and descriptions.

The name of a Text object should be derived from the name of the Output object it is used in. When used in multiple outputs, its name should provide information about what is being played. The table below lists two examples:

Name	Description
Welcome	Welcome message for the main menu
Generic No Match	Contains five alternatives for a generic No Match prompt (e.g. Sorry? Your input did not match the expected format.).