XDK Overview

Introduction

With XDK, the XML Development Kit, VoiceObjects provides the voice market’s first open, XML-based interface to its phone application server. XDK enables developers to use the Integrated Development Environment (IDE) of their choice, such as Eclipse, SAP NetWeaver Studio, or IBM WebSphere Studio, while still retaining full access to the object-oriented design approach provided by VoiceObjects.

At the heart of XDK stands VoiceObjectsXML, an XML-based application-level markup language. It sits on top of open standard such as VoiceXML or SALT, yet is independent of individual media platforms, owing to the VoiceObjects media platform driver concept. Furthermore, it provides all the powerful capabilities built into VoiceObjects’ patented object technology such as a true object-oriented development approach and inheritance.

Application Development

Applications may be developed in XDK using any Integrated Development Environment (IDE) of choice. A Document Type Description (DTD) and XML schema are provided to enable validation and such features as auto-completion.

A VoiceObjectsXML application definition may consist of multiple files, one of which needs to be the root file from which all others are referenced. Additional files can be imported using the following notation:

<xi:include href=”../lib/myobjects.xml”/>

The href reference may use relative or absolute file or HTTP URLs. Relative URLs are resolved relative to the location of the parent file.
Imports may only be defined at the beginning of a file, before any object definition. Objects may be referenced across different files. Before performing a validity check, all files are merged to determine the total set of objects.

Each individual document needs to be wrapped in

8 Caution: All referenced VoiceObjectsXML files must have the same version information set. A mix of different VoiceObjects versions is not supported as it might lead to problems on importing and deploying.

The file encoding needs to be specified in the <xml> header line, e.g.

<?xml version="1.0" encoding="ISO-8859-1"?>

Top-level elements

The following table lists the available top-level VoiceObjectsXML elements. They correspond to the objects of the same name, and are described in detail in the Object Reference.

Element	Description
<audio>	Defines an Audio object. Uses embedded <altText>.
<businessTask>	Defines a Business Task object.
<case>	Defines a Case object. Uses embedded <caseItem>.
<collection>	Defines a Collection object.
<confirmation>	Defines a Confirmation object. Uses embedded <correctionItem>.
<connector>	Defines a Connector object. Uses embedded <connectorItem>.
<database>	Defines a Database object.
<exit>	Defines an Exit object.
<expression>	Defines an Expression object. Uses embedded <argument>.
<format>	Defines a Format object. Uses embedded <formatItem>.
<goto>	Defines a Goto object.
<grammar>	Defines a Grammar object. Uses embedded <grammarItem>.
<hyperlink>	Defines a Hyperlink object.
<if>	Defines an If object.
<input>	Defines an Input object. Uses embedded <resultHandling>.
<layer>	Defines a Layer object. Uses embedded <layerState>.
<list>	Defines a List object. Uses embedded <contentFormatting>, <columnGroup>, <navigationMessages>, <selectionCommands>.
<log>	Defines a Log object. Uses embedded <logItem>.
<loop>	Defines a Loop object.
<menu>	Defines a Menu object. Uses embedded <menuItem>.
<module>	Defines a Module object.
<osdm>	Defines an OSDM object. Uses embedded <osdmItems>.
<output>	Defines an Output object. Uses embedded <outputItem>.
<pause>	Defines a Pause object.
<plugin>	Defines a Plug-In object. Uses embedded <parameterSet>, <value>.
<recording>	Defines a Recording object. Uses embedded <parameterSet>.
<resourceLocator>	Defines a Resource Locator object.
<script>	Defines a Script object. Uses embedded <parameterSet>, <value>.
<sequence>	Defines a Sequence object.
<silence>	Defines a Silence object.
<text>	Defines a Text object.
<transfer>	Defines a Transfer object. Uses embedded <parameterSet>.
<variable>	Defines a Variable object.
<video>	Defines a Video object.

Embedded elements

The top-level elements make use of the following embedded elements:

Element	Description
<argument>	Defines arguments for expressions.
<eventHandling>	Defines event handling.
<item>	Defines individual entries in parameter sets or result handling.
<osdmItems>	Defines parameterization for OSDM objects.
<parameterSet>	Defines parameter sets.
<resultHandling>	Defines result handling for inputs.
<standardNavigation>	Defines standard navigation.
<tuning>	Defines tuning settings.
<value>	Wraps embedded code for plug-ins or scripts, or embedded values for variables, collections, and expression arguments.

Standard attributes

The top-level VoiceObjectsXML elements carry certain standard attributes, all of which are optional. The following table provides an overview of these attributes and their uses.

Attributes listed in the descriptions for the individual XML elements are to be seen in addition to the standard attributes. They are optional unless marked as “required”.

Attribute	Description
name	Name of the object. Can be used to refer to the object within XDK files. No two elements of the same type may have the same name.
referenceID	Reference ID of the object. A text string without blanks or special characters other than underscores. Maximum length is 256 bytes. No two elements in an application may have the same reference ID, regardless of type.
guid	Globally unique ID for the object. Unless this is specified, a new ID is generated whenever a VoiceObjectsXML application is deployed to VoiceObjects Server or imported into the VoiceObjects Metadata Repository. GUIDs are conceptually like reference IDs, and an object may have the same reference ID and GUID. No two elements in an application may have the same GUID, regardless of type. GUIDs must be of the form OVAPxxxxx where xxxxx is a string of exactly 40 characters from among a-z, A-Z, 0-9.
shortDescription	A text string defining the short description of the object. Maximum length is 4,000 bytes.
comment	A text string defining a comment for the object. Maximum length is 8,000 bytes.
keywords	A text string defining the keywords for the object (for searching). Maximum length is 4,000 bytes.
versionDescription	A text string defining the version description of the object. Maximum length is 8,000 bytes.
errorDescription	A text string defining the error description of the object. Maximum length is 4,000 bytes.
disable	Either true or false. Indicates whether the object is disabled or not. If not specified, defaults to false. This attribute is not available for those object types that cannot be disabled (<format>, <resourceLocator>, <variable>, <collection>, <layer>).
link	A reference to another object of the same type. References begin with the # character and may use either the object’s name or the object’s reference ID. Objects may be referenced across file boundaries. When resolving references, an object of the same type with the given string as name is searched for first. If no such object exists, then an object of the same type with the given string as reference ID is searched for. If no such object exists either, an error message is produced. If a link is specified, all other attributes (except usage and type), and all children are ignored. Objects from libraries can be linked using the notation object://LibraryName/LibraryVersionName#ObjectName
usage	Indicates how this element is used as a child of another element. This is relevant when an element may have several children of the same type. Legal usage types are listed in the DTD and indicated in this document. This attribute is only available on those object types that require it.

i8 Note: In case of the attributes name, shortDescription, comment, keywords, versionDescription, and errorDescription using UTF-8 characters is allowed, but may reduce the given size limit, as some characters use more than one byte.

i8 Note: When using MaxDB as the Metadata Repository DBMS the following limits apply to the size of the standard properties described above:
referenceID: 255 bytes; shortDescription: 500 bytes; comment: 500 bytes; keywords: 255 bytes; versionDescription: 500 bytes; errorDescription: 255 bytes.

Object references

Objects are referenced in VoiceObjectsXML by their name to enhance readability. Since most references combine object type and object name as e.g. in

</sequence>

there is no confusion because no two objects of the same type may have the same name.

When objects are referenced in attributes, a “type hint” can optionally be added to eliminate confusion between objects of equal name but different type:

Objects from libraries can be referenced using the fully qualified object notation:

…

</module>

Application Deployment

Applications developed within XDK are deployed to VoiceObjects Server as services. This can be done using VoiceObjects Desktop and the Web Services Interface.

8 Caution: When using Infostore in conjunction with XDK applications, make sure to provide reference IDs and names for all Module objects in your application. Otherwise, reports on application usage will suffer from inconsistent object IDs.

VoiceObjects Desktop deployment

XDK applications can be referenced directly from within services created within VoiceObjects Desktop by using a URI as start object definition. Upon (re-) deployment of the service, the application is dynamically loaded by the server.

For more information, refer to the Deployment Guide.

Web services deployment

Services can be deployed through the Web Services Interface as standard services using the deployXDKService method, or as volatile services using the redeployXDKApplication method. The difference in the latter case is that no intermediate files need to be generated from which the application definition is loaded.

For more details, refer to the Web Services Guide.

Configuration Objects

All VoiceObjects configuration objects (servers, services, users, and projects) can also be defined using VoiceObjectsXML markup. The subsequent paragraphs describe how to define the different object types.

i8 Note: Only a single type of configuration object may be defined within one XDK file, but multiple objects of the same type can be defined at once.

Servers

Servers are configured using the <server> element. It has two children <serviceList> (described below) and <accessControlList> (described in Users and access control) and the following attributes (in addition to the standard attributes, of which referenceID is mandatory):

Attribute	Description
sessionLimit	Defines the maximum number of concurrent sessions for this server.
sessionGuarantee	Defines the guaranteed number of concurrent sessions for this server.
systemDBLogging	Defines whether System DB logging is enabled for this server. Either true or false. If not specified, defaults to true.
customDBLogging	Defines whether Custom DB logging is enabled for this server. Either true or false. If not specified, defaults to true.
utteranceRecording	Defines whether utterance recording is enabled for this server. Either true or false. If not specified, defaults to true.

<serviceList> may contain any number of <service> children defining the list of services hosted on the server. The services can either be defined inline, or they can be referenced using the link attribute. When a service is referenced using the link attribute, the corresponding Service object must already exist in the Metadata Repository.

i8 Note: When using an inline definition of a service, this service must not exist in the Metadata Repository. Otherwise an error message will be returned when importing the server definition.

Any number of servers may be defined in a single XDK file.

Example:

<server name=”Production Server” referenceID=”VOServer”

systemDBLogging=”true” customDBLogging=”false”/>

Services

Services are configured using the <service> element. It has one child <accessControlList> (described in Users and access control) and the following attributes:

Attribute	Description
name	Name of the Service object (for display in VoiceObjects Desktop).
vsn	VoiceObjects Service Name for the service. Mandatory.
link	A reference to another service, either by name or by VSN. References begin with the # character. If a link is specified, all other attributes (except usage and type), and all children are ignored.
startObject	Start object for the service, to be provided as a URL. Note that the start object itself must be designated by its reference ID, not by its name.
enableValidation	Indicates whether the application should be validated when loading the cache. Either true or false. If not specified, defaults to true.
retainOnShutdown	Indicates whether the application cache should be persisted even when the server is completely shut down. Either true or false. If not specified, defaults to false.
cacheStandby	Indicates whether the application cache for this service may be dropped from memory. Either onDemand or never, defaults to onDemand.
dnisMapping	Comma-separated list of DNIS that map to this service.
startupMode	Defines the start-up mode for the service. One of automatic, disabled, manual. If not specified, defaults to automatic.
respectUserAgent	Indicates whether the server should attempt to derive the appropriate driver from the user-agent information contained in the initial request. Either true or false. If not specified, defaults to false.
language	Defines the initial language setting for the service. 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 in the Object Reference contains a list of all language codes available in VoiceObjects together with the respective language they represent.
driver	Defines the media platform driver for the service. Can be default or a valid media platform driver code, e.g. Avaya_VP_4_0_VXML_2_1_ASR_Nuance (see the Deployment Guide or the DTD or XSD for a list of all available drivers). If not specified, defaults to default.
sessionLimit	Defines the maximum number of concurrent dialog sessions that is allowed for this service.
sessionGuarantee	Defines the number of guaranteed sessions that should be set aside for this service.
sessionDistribution	Defines the distribution of dialog sessions between services within the same custom site. Either disabled, or a float value between 0 and 1 indicating a percentage (e.g. 0.75 for 75%). If not specified, defaults to disabled.
maintainer	E-mail address of the application administrator. Is used by the media platform to send e-mail in case of errors.
loggingDestination	Defines the default logging destination for Custom DB logging. One of file, customDB, mediaPlatform, systemDB, logOSDM. If not specified, defaults to file.
loggingCategories	Defines the active logging categories for Custom DB logging. Comma-separated list of values from among info, debug, error, statistics, billing. If not specified, all of the categories are enabled.
systemDBLogging	Defines whether System DB logging is enabled. Either true or false. If not specified, defaults to false.
customDBLogging	Defines whether Custom DB logging is enabled. Either true or false. If not specified, defaults to false.
inputStateLogging	Defines whether Input State logging is enabled. Either true or false. If not specified, defaults to false.
loggingCoverage	Defines the percentage of dialogs that should be written to System DB logging. Can be a float value between 0 and 1 indicating a percentage (e.g. 0.75 for 75%). If not specified, defaults to 1.
filterScope	Defines whether the logging coverage extends only to input states, to System DB logging, or to System and Custom DB logging. One of inputState, systemDB or systemDBCustomDB. If not specified, defaults to systemDB.
enableUtteranceRecording	Defines whether utterance recording is enabled. Either true or false. If not specified, defaults to false.
recordUtterances	Defines the default value for the recordUtterances setting on dialog objects. Either true or false. If not specified, defaults to true.
recordingScope	Defines whether utterance recording files are created only for recognized utterances (recognition), for utterances that lead to No Match events (noMatch), or for both (all). If not specified, defaults to all.
utteranceRecordingPath	Defines the path that utterance recording files are written to.
utteranceRecordingURL	Defines the URL through which utterance recording files can be retrieved.
recordingCoverage	Defines the percentage of dialogs that should write utterance recording files. Can be a float value between 0 and 1 indicating a percentage (e.g. 0.75 for 75%). If not specified, defaults to 1.
bargein	Defines the default value for barge-in behavior. Either true or false. If not specified, defaults to true.
grammarType	Defines the default grammar type. Must be one of default, abnf, gsl, jsgf, xml, cisco, precompiled, none. If not specified, defaults to default.
grammarPrecedence	Defines the precedence between embedded and external grammar definitions within Grammar objects. Either embedded:external or external:embedded. If not specified, defaults to embedded:external.
outputMode	Defines the default output mode. Either audio:tts or tts:audio. If not specified, defaults to audio:tts.
inputMode	Defines the default input mode. One of voicedtmf, voice, or dtmf. If not specified, defaults to voicedtmf.
exitType	Defines the default dialog exit type. Can be disconnect, exit, or return. If not specified, defaults to disconnect.
videoType	Defines the default video type. One of default, video, videoaudio, none. If not specified, defaults to default.
dialogTimeout	Defines the dialog timeout. An integer value that is interpreted as seconds. If not specified, defaults to 300 (5 minutes).
standbyTimeout	Defines the default standby timeout. An integer value that is interpreted as seconds. If not specified, defaults to 600 (10 minutes).
connectorTimeout	Defines the default connector timeout. An integer value that is interpreted as seconds. If not specified, defaults to 60 (1 minute).
standardNavigationHistory	Defines the length of the dialog navigation history for the service. Can be disabled, or an integer between 1 and 10. If not specified, defaults to 3.
audioFileExtension	Defines the standard audio file extension. Legal values are none, wav, aif, aiff, dwd, mp3, snd, au, voc, vox. If not specified, defaults to none.
grammarFileExtension	Defines the standard grammar file extension. Legal values are none, abnf, grammar, grm, grxml, gsl, jsgf. If not specified, defaults to none.
videoFileExtension	Defines the standard video file extension. Legal values are none, 3gp, 3g2, mp4, mp4v, m4v, rtp, bmp, gif, jpg, jpeg. If not specified, defaults to none.
textFileExtension	Defines the standard text file extension. Legal values are none, txt. If not specified, defaults to none.
rejectResponse	Defines the response behavior for dialogs that are rejected due to missing licenses. Either overflow or redirect. If not specified, defaults to overflow.
proxyHost	Defines a proxy host to use for HTTP connectors. If not specified, no proxy is used.
proxyPort	Defines a proxy port to use in combination with the proxy host. Only relevant if proxyHost is defined.
resourceLocatorPath	Defines a physical path that overwrites the respective entries in resource locators with the option allowServiceOverwrite enabled. If not specified, the local entries of all resource locators are used.
loopAbortHandlerURL	Defines the location of a file holding valid VoiceXML code that will be used as the loop abort handler.
configurationURL	Defines the location of a configuration file that defines application default values.
resourceLocatorURL	Defines a URL that overwrites the respective entries in resource locators with the option allowServiceOverwrite enabled. If not specified, the local entries of all resource locators are used.
osdmURL	Defines a URL that points to the OSDM installation to be used by OSDM objects.
osdmEventLogging	Indicates whether OSDM event logging is enabled. Either true or false. If not specified, defaults to false.
osdmEventLogDestination	Defines the file to which OSDM event logging should be written. If not defined, the default OSDM event logging destination as defined by the OSDM installation is used.
shortDescription	A text string defining the short description of the service.
errorDescription	A text string defining the error description of the service. Maximum length is 4,000 bytes.
versionDescription	A text string defining the version description of the service. Maximum length is 8,000 bytes.
comment	A text string defining the comment for the service.
keywords	A text string defining the keywords for the service.

Multiple services may be defined in a single XDK file, wrapped in the <serviceList> element.

Example:

Users and access control

Users are configured using the <user> element. It has one child <accessControlList> (described below) and the following attributes (in addition to the standard attributes):

Attribute	Description
userID	Defines the user ID for this user. This replaces the standard referenceID attribute, and is required.
password	Defines the password for this user.
email	Defines the e-mail address for this user
role	Defines the user role. One of reviewer, designer, serviceController, observer, siteController, siteAdministrator, userManager, serverController, serverAdministrator. If not specified, defaults to designer.
accountStatus	Defines whether the account is active or not. Either active or inactive. If not specified, defaults to active.
allowPasswordChange	Defines whether the user is allowed to change his password (true or false), or whether the password needs to be changed on next login (login). If not specified, defaults to login.
allowProjectCreation	Defines whether the user is allowed to create new projects. Either true or false. Note that this value may be irrelevant, depending on the selected user role. If not specified, defaults to true.
allowWSIAccess	Defines whether the user is allowed to access the Web Services Interface. Either true or false. If not specified, defaults to true.
auditDesktop	Defines the audit level for user interactions with VoiceObjects Desktop. One of none, all, denied. If not specified, defaults to none.
auditServer	Defines the audit level for user interactions with VoiceObjects Server. One of none, all, denied. If not specified, defaults to denied.
auditWSI	Defines the audit level for user interactions with the Web Services Interface. One of none, all, denied. If not specified, defaults to denied.
The attributes listed below are only relevant if the user is the root Site Administrator for a custom site. In this case, they define settings that are applied in the entire site.
siteID	Defines the name of the site. If not defined, the user ID of the root Site Administrator of the site is used.
basePath	Defines a base physical path used for all resource locators in applications within the site.
baseURL	Defines a base URL used for all Audio, Video, Grammar, and Plug-In objects in applications within the site.
connectorURL	Defines a base URL used for all Connector and Script objects in applications within the site.
importPath	Defines a base import/export path used for the site.
startObjectPath	Defines a base URL used for the start objects of all XDK-based services in the site.
utteranceRecordingPath	Defines the base path used for writing utterance recording files in the site.
utteranceRecordingURL	Defines the base URL through which utterance recording files can be retrieved in the site.
sessionGuarantee	Defines the guaranteed number of concurrent sessions for the site.
sessionLimit	Defines the maximum number of concurrent sessions for the site.
serverLimit	Defines the maximum number of concurrently active servers for the site.
serviceLimit	Defines the maximum number of concurrently active services for the site.
designerSeats	Defines the maximum number of Designer seats available within the site.
siteSeats	Defines the maximum number of Site seats available within the site.
seats	Defines the maximum number of VoiceObjects Desktop seats available within the site.
osdm	Indicates whether OSDM support is available within the site. Either true or false. If not specified, defaults to false.
infostore	Indicates whether Infostore is available within the site. Either true or false. If not specified, defaults to true.

Access control lists for objects are defined using the <accessControlList> element. It has one child <aclEntry>, which in turn has an attribute user that references a User object through its userID.

Any number of users may be defined in a single XDK file.

Example:

Projects

Projects are configured using the <project> element. It has two children <accessControlList> (optional) and <projectVersion> (mandatory), and the standard attributes of which name is mandatory.
In addition, the <project> element has an attribute isLibrary, which can be true or false (the default). The isLibrary attribute is only interpreted the first time a project is created and cannot be modified later on.

A project version is configured using the <projectVersion> element. It has one optional child <libraries> and the standard attributes, of which name is mandatory. When creating a project, exactly one project version must be created. New project versions can only be created by publishing existing ones. For more information, refer to the Web Services Guide.

Libraries are attached to project versions using the <libraries> element. It may contain one or more <library> children. Each <library> has two mandatory attributes libraryName and libraryVersionName.

Any number of projects may be defined in a single XDK file.

Example:

</project>

</accessControlList>

</libraries>

</projectVersion>

</project>

Importing into the VoiceObjects Metadata Repository

Applications developed in XDK can be imported into the VoiceObjects Metadata Repository through VoiceObjects Desktop or through the Web Services Interface. This is done using the standard import mechanism described in Chapter 7 – Basic Commands in the Desktop for Eclipse Guide and Desktop for Web Guide, and in the Web Services Guide.

@8 Tip: When you intend to import your XDK application into the VoiceObjects Metadata Repository, you should define the name attribute for all objects. For objects that do not have a name defined, a name is constructed during the import process based on the name of the XDK file and the line number in which the object definition starts (e.g. HelloWorld.xml_17). The resulting application is fully functional, but not very readable.

In addition to applications, it is also possible to import configuration objects into the Metadata Repository.