This chapter describes the actions that can be performed using the Web Services Interface (WSI). All object representations and modifications require knowledge of VoiceObjectsXML. It is therefore strongly recommended to read through the XDK Guide and the relevant parts of the Object Reference when working with the WSI.

Creating New Objects

New objects can be created through the Web Services Interface by supplying the definition in VoiceObjectsXML. Through appropriate methods, configuration objects as well as dialog objects can be built and imported into the Metadata Repository. All import and create methods provide a parameter isURI. If this parameter is set to false, the WSI expects the object definition as a character string. Alternatively you can provide the URI to a file containing the definition. In this case the parameter isURI must be set to true. Valid URIs can be specified by using either the file or the HTTP protocol:

file:///\\<hostname>\<directory>\<filename>

http://<hostname>:<port>/<directory>/<filename>

i8    Note: As the server will use the given URL to retrieve the VoiceObjectsXML document, you have to make sure that the given file is accessible from the machine hosting the server.

Configuration objects

The WSI provides dedicated create methods for every type of configuration object. The create methods can be used to create new objects in the Metadata Repository. If you want to create a new object you have to make sure that no object of the same type and name, or of a different type but the same reference ID exists. If it does, a corresponding error message will be returned and the new object is not created.

To prevent overwriting of existing objects the parameter overwrite should be set to false. If this parameter is set to true, an existing object with the same reference ID will be deleted before the new object can be created.

8     Caution: If the new object cannot be created (e.g. because of an invalid XML definition) the existing object is still removed from the Metadata Repository.

Dialog objects

New dialog objects (i.e. objects of all object types within the categories Components, OSDMs, Resources, Logic, Action, Layer, and Business Task; for details see the Object Reference) can be imported into an existing project version by using the importObject method. If a naming conflict occurs during the import because an object of the same type and name already exists in the project, VoiceObjects automatically appends a time stamp to the name of the newly imported object. By setting the parameter overwriteByName to true, existing objects of the same name and type will be overwritten.

Modifying Existing Objects

Modifying an object will only change specific properties that are given in the VoiceObjectsXML definition. All other values will stay unchanged. It is not possible to change an object’s GUID.

Configuration objects

There are dedicated modify methods for every type of configuration object. The modify methods will change the definition of existing configuration objects. The modified object definition must be specified in VoiceObjectsXML. Properties that are not specified in the XML will stay unchanged.

Dialog objects

To modify existing dialog objects or complete applications, the method importObject should be used. If your application definition contains GUIDs, objects with the same GUID will be overwritten. By setting the parameter generateNewGuids to true, new GUIDs will be created for the imported objects.

If your application does not contain GUIDs and the parameter overwriteByName is set to true, existing objects with the same name and type will be overwritten.

Change access control lists

Access control lists (ACLs) define which users are allowed to access and modify individual objects. To add or remove user entries from the ACL of an object the methods addUserToACL and removeUserFromACL can be used, respectively.

To modify the complete ACL at once, the modify methods or the method importObject can be used. In this case the object definition must contain a valid ACL in its VoiceObjectsXML definition. Due to security restrictions the user executing the modify or importObject command might not be allowed to view existing ACL entries. When importing, these entries will not be removed but only the new entries will be added.

Deploying Applications

Depending on the location of the application definition, there are several ways to deploy a service on a server.

Deploy from file

If both the service definition and the application definition are available as XDK files, the method deployXDKService can be used. This method creates a Service object from the given service definition and adds it to the list of services hosted on the server. The method reloadServiceList must be executed afterwards to reload the service list on the server.
If a service with the given VSN already exists in the Metadata Repository, the existing Service object will be overwritten. If, in addition, this service already was on the service list of the server, the method redeployService has to be executed instead of reloadServiceList.

Deploy from string

If the application definition is not persisted as a file or the server does not have access to the location of the file, the method redeployXDKApplication can be used to create a “volatile” service.

Before the method redeployXDKApplication can be used, a Service object must be created and added to the list of services hosted on the server. The start object of this service can be left empty. Once the service is shown on the list of services (returned by the queryServer method) the method redeployXDKApplication can be called. The parameter applicationDefinition must contain the application as a VoiceObjectsXML string.

i8    Note: A service can only act as a volatile service if it has the option retainOnShutdown set to true. Otherwise, the method redeployXDKApplication will return an error message (with code 800400004).

A volatile service can only be redeployed by using the redeployXDKApplication command. Executing the method redeployService on such a service has no effect.

Deploy from VoiceObjects Desktop project

If you want to deploy a service from a VoiceObjects Desktop project, you can also do so by using the appropriate WSI methods.

When creating the service you have to specify the start object by using the following syntax:

project://<Project name>/<version name>/#<Start Object Reference ID>

This URL must point to an existing object inside the specified project version. After the service is created successfully, you need to add this service to the list of services hosted on the server and reload the services list.

Controlling Servers and Services

To control and monitor the states of your servers and services, the Web Services Interface provides dedicated methods.

Retrieve a list of active servers

To get a list of active logical servers in your environment the method getServerList can be used. This method returns all currently running servers that belong to the same cluster group as the Web services provider that is called.

From the returned XML structure the reference ID of one or multiple servers can be retrieved to query the servers and modify their states.

Query a specific server

The queryServer method can be used to get an overview of a specific server, its server instances and deployed services. The return XML shows detailed information about the currently active settings of the server, server instances and services, such as the status of e.g. DB logging and tracing. It also includes statistics information about active, finished, aborted and rejected sessions per server, service and server instance.

By using this command you can monitor the status of your environment and check the current load of your server instances and services.

State changing commands

There are several methods available to modify the states of servers and services. These commands are executed in a synchronous manner. This means that upon execution the method will poll the server until the specified state has been reached or an error occurred. For example the idleServer method will only return after the server has reached the idled state.

Especially when using server management methods, such as resetServer or stopServer, you should execute the method queryServer to make sure all server instances have reached the expected state.