3 Managing Servers and Services
Control Center
The Control Center is the graphical interface component within VoiceObjects Desktop that enables the deployment and monitoring of servers and services.
As an alternative to the graphical Control Center, the Web Services Interface may be used. Details can be found in the Web Services Guide.
There is also a text-based Command Line Interface (CLI), which is explained in Chapter 7 – Command Line Interface (CLI). It is recommended, however, to use the Web Service Interface instead since it provides more flexibility.
Finally, notifications about specific conditions on servers can be received through SNMP and e-mail as explained in Chapter 8 – Notifications.
Desktop for Eclipse Control Center
To open the Control Center for a given server in Desktop for Eclipse, first a corresponding Control Center connection has to be defined in the VoiceObjects preferences of Desktop for Eclipse. Refer to Configuring a Control Center Connection in Chapter 10 – VoiceObjects Preferences in the Desktop for Eclipse Guide for details on how to do this.
Once one or more Control Center connections have been configured the Control Center will be shown, initially located at the bottom of Desktop for Eclipse.
The drop-down box in the upper right corner allows switching between the configured Control Center connections.
Using the Filter field you can restrict a list of server and server instances, services, log files, or trace files to those items that contain a certain text string within their name, or that have a name starting with a certain text string (when selecting the Starts with check box).
The content of the Control Center is automatically refreshed to show the currently active service states, call statistics, etc., according to the refresh cycle, which can be specified in the Advanced preferences page. A manual refresh can be activated by clicking the Refresh button 
in the upper right corner of the Control Center.
Below the header bar, the Control Center displays six tabs. Server Manager and Service Manager are explained in this chapter, Server Logs, Service Logs, and Session Tracing are described in Chapter 5 – Logging and Tracing, and Session Partitioning is described in Chapter 9 – Service Level Agreements (SLA).
Desktop for Web Control Center
In Desktop for Web the Control Center for a given server can be opened by doing the following:
1. In the Object Browser, open the Configuration folder and then the Server folder. You need to have a Controller or Administrator role to see the Configuration folder.
2. Right-click the Server object for which you want to open the Control Center. And in the context menu that comes up, click Control Center.
Note that to open the Control Center it is necessary to configure the appropriate Control Center URL within the Server object. For details, see Chapter 2 – Configuring Servers and Services.
The Control Center is loaded into a new tab in the right-hand pane of VoiceObjects Desktop. If this tab already exists, the view switches to it.
In the header bar of the Control Center, the display Refresh Cycle can be selected in various intervals between thirty seconds and one hour. After a refresh cycle has expired, the display of the Control Center is automatically refreshed to display the currently active service states, call statistics, etc. A manual refresh can be activated by clicking the Refresh button 
in the menu bar of VoiceObjects Desktop.
Below the header bar, the Control Center displays five tabs: Server Management (see Server Manager and Service Manager below) is explained in this chapter, Server Logs, Service Logs, and Session Tracing are described in Chapter 5 – Logging and Tracing, and Session Partitioning is described in Chapter 9 – Service Level Agreements (SLA).
Control Center communication
VoiceObjects uses the Web Service Interface to communicate between the Control Center and servers that are monitored and controlled by it. This has the advantage that VoiceObjects Desktop does not need to be part of the same cluster as the server to be monitored, and that both local servers (within the same network) and remote servers (in other networks) can be monitored and controlled. Finally, even servers running on different Metadata Repositories can be monitored and controlled. This makes it possible, for instance, to administrate both a test and a production installation from a single VoiceObjects Desktop.
@8 Tip: The Control Center remembers all server instances that were present at some time during the current session (i.e. as long as the Control Center is open) and tries to re-connect to any of them when the server instance it is currently connected to becomes unavailable. This means that when you shut down instances in a cluster, you do not need to manually adjust the URL defined in the Server object. A manual refresh of the Control Center may be required at times to trigger the re-connect to a different server instance.
When you open a new Control Center, it always tries to connect to the server instance reachable at the URL defined in the Server object. If this fails, you will see an error message. In this case, adjust the URL to an available server instance and try again.
Server Manager Overview
The Server Manager tab displays detailed information about the server and all running server instances.
In Desktop for Web this information can be found in the Server Manager section of the Server Management tab.
The Server column shows the logical name of the server, which corresponds to the reference ID of the Server object. Each server instance is represented by its name, or by its IP address and port (as configured in the corresponding configuration file). To better separate the server from the server instances, a prefix “S:” for the server and “I”: for the server instances is added to their names. Desktop for Web does not add any prefix as here the server is visually separated from the server instances. In a single server setup, only one instance is available. In a cluster setup, it may be any number of instances.
To the left of the Server column, the server and server instance status is indicated by a traffic light icon:
Icon |
Server Status |
|
|
Started |
|
|
Idled |
|
|
Stopped |
If one of the server instances listed acts as master server manager for the cluster, this is indicated by the Crown icon 
next to the traffic light icon.
i8 Note: There may be cases in which none of the server instances acts as master server manager, because this role is taken by a server instance of a different server. Thus, if you do not see a crown icon next to any of the server instances this does not necessarily indicate a problem.
Refer to Server Management and Server Instance Management below for more details about the shown information as well as on the available control functions for the server and the server instances.
Server Management
This paragraph describes the server statistics shown in the nine additional columns of the Server Manager tab, all commands available in the server context menu and the Server Details info box providing a summary of various server information.
Server statistics
To the right of the Server column, the next set of six columns provides session statistics for the server, displaying:
· Start Time
Indicating the most recent time the server has been (re-)started. In the case of a cluster, the start time indicates the earliest start time of any of the individual server instances involved.
· Active
Number of currently active sessions on this server.
· Finished
Number of sessions on this server that were completed successfully.
· Aborted
Number of sessions on this server that were aborted due to an error condition (including dialog timeout).
· Rejected
Number of sessions on this server that were rejected. This may happen because the corresponding service was not started when the session came in, or because no matching service could be found for the VSN and/or DNIS provided. It may also happen when no more concurrent sessions are available for a certain service, server, site, or the entire VoiceObjects installation.
· Total
Sum of the previous four columns.
The following two columns, System DB Logging and Custom DB Logging, indicate the currently applicable DB logging options for the server as enabled (green light 
), disabled (red light 
), unavailable (yellow light 
), or not licensed (grey light 
).
DB logging requires a valid license for Infostore.
i8 Note: While the red or green light indicates a specific administrator setting, the yellow light indicates that the respective logging option should be enabled, but failed due to a database connection problem. In order to resolve this, the respective server instance needs to be fully restarted (including its JVM) once database connectivity has been restored.
The grey light indicates that the license key for the server does not allow DB logging. Contact VoiceObjects regarding a license for Infostore.
The final column Tracing indicates whether tracing is currently enabled (green light ) or disabled (red light ) for this server. More information on tracing is provided in Chapter 5 – Logging and Tracing.
Server context menu
To access server control functions, right-click anywhere in the row of the server entry. In Desktop for Web click the Context Menu button 
to the right of the server name. The following list describes the server control functions that are available from the context menu. Note that most of them are only available to Server Administrators or Server Controllers. Other user roles only see a subset of the functions. For more information on user roles and their privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide.
· Edit
Opens up the Server editor. Note that this entry is only available if the Server object for which the Control Center is shown comes from the Metadata Repository to which Desktop for Eclipse is currently connected. In addition the user account used for both the connections needs to be the same.
· Reload Service List
Reloads the list of services hosted on this server. This is used when you have added a new service to a server, or removed a service from a server.
After reloading the service list, the Control Center will display any newly added services as stopped (see description of service states below). You need to start the service before it can be called.
Services that have been deleted from the server will only be removed from the Control Center if they have been stopped before reloading the service list.
· Start
Starts this server. For a cluster this means that all individual server instances in the cluster are started.
This command is only available when the server is stopped. Note that when starting a stopped server, all active and restore caches are restored from their previously persisted state, and application definitions are not reloaded from scratch. Services will be started according to their startup mode, i.e. services with startup mode automatic will be started and services with startup mode manual (or disabled) will remain stopped.
· Resume
Resumes this server. For a cluster this means that all individual server instances (both idled and stopped) in the cluster are resumed.
This command is only available when the server is idled. When resuming an idled server, all idled services are also resumed.
· Reset
Resets this server to essentially the state it would be in immediately after a fresh start. The difference is that if a redeploy would break a currently running service, then it is kept in its current state. After a reset, all restore caches are gone.
For a cluster, Reset means that all individual server instances in the cluster are reset. A warning window will appear to indicate that all currently active sessions will be terminated immediately. If you confirm by clicking OK, all currently active sessions are terminated, and the server resets. During reset, all services are stopped and their application caches are loaded. If the server was started, the services are then started according to their startup mode settings.
This command is only available when the server is started or idled.
· Idle
Idles this server. For a cluster this means that all individual started server instances in the cluster are idled. A warning window will appear to indicate that the server will be idled. This does not affect currently active sessions, which are allowed to finish normally. If you confirm by clicking OK, the server attempts to idle and the Control Center shows the “Please wait” icon. When the server reaches idled state (after all active sessions on the server have terminated), the server’s status light changes to solid yellow.
This command is only available when the server is started.
· Stop
Stops this server. For a cluster this means that all individual server instances in the cluster are stopped. A warning window will appear to indicate that all currently active sessions will be terminated immediately. If you confirm by clicking OK, all currently active sessions are terminated, and the server stops.
When the server stops, all services hosted on it also stop. Their persisted active and restore caches remain intact. When you start the server again using the Start command, these caches are restored.
· Shutdown
Shuts down this server. For a cluster this means that all individual server instances in the cluster are shut down. A warning window will appear to indicate that all currently active sessions will be terminated immediately. If you confirm the shutdown by clicking OK, all currently active sessions are terminated, and the server shuts down.
When the server shuts down, all active and restore caches are cleaned (except for those services that explicitly use the Retain caches on shutdown option). The server cannot be started up again from within the Control Center or CLI after it has been shut down. The server process needs to be re-started manually.
i8Note: Shutting down the server will not stop the JVM it is running in.
· DB Logging Options
Used to modify the currently applicable DB logging configuration for the server.
In the cascading submenu that comes up, both System DB logging and Custom DB logging can be enabled or disabled by clicking the respective entry. Changes made here have immediate effect, but they do not change the permanent settings made in the Server object. The modified status is indicated by the appropriate lights in the System DB Logging and Custom DB Logging columns as well as by a tick mark (or its absence) in the context menu itself.
DB logging settings made in the server override those made in services that are hosted on this server. Thus by disabling System or Custom DB logging on the server, it is automatically disabled for all services. This override is indicated by a black light (
) in the respective DB Logging column for the service.
Note that when resetting a server, the default values defined in the Server object are restored.
· Disable/Enable Tracing
Used to modify the currently applicable tracing configuration for the server.
By clicking the context menu entry, tracing can be enabled or disabled. Changes made here have immediate effect. The modified status is indicated by the appropriate light in the Tracing column as well as by a tick mark (or its absence) in the context menu itself.
The tracing setting made in the server overrides those made in services that are hosted on this server. Thus by disabling tracing on the server, it is automatically disabled for all services. This override is indicated by a black light () in the Tracing column for the service.
Note that after resetting a server, tracing is enabled by default.
· Details (only available in Desktop for Eclipse)
Opens up the Server Details with the Server tab in front showing a summary of server information. In Desktop for Web the info box is opened by clicking the Maximize button 
at the right end of the row. Refer to Server details below for details on the information that is displayed.
· Refresh (only available in Desktop for Eclipse)
Used to manually refresh the Control Center to display the currently active service states, call statistics, etc. In Desktop for Web the Refresh button in the menu bar can be used instead.
· Properties (only available in Desktop for Web)
Opens up the Properties window of the Server editor.
· Reports (only available in Desktop for Eclipse)
Provides a cascading submenu of reports available for the server. For details, refer to Appendix B – Control Center Reports.
This command is only available if Infostore is enabled for the server.
Server details
The Server Details info box can be opened by double-clicking the server entry on the Server Manager tab or by selecting Details from its context menu.
In Desktop for Web the info box is opened by clicking the Maximize button at the right end of the row.
The Server Details info box opens up showing the Server tab in front.
It provides a summary of the following information about the server:
· System DB Logging
Shows the status of System DB logging, which is also indicated by the appropriate light in the System DB Logging column in the Control Center.
· Custom DB Logging
Shows the status of Custom DB logging, which is also indicated by the appropriate light in the Custom DB Logging column in the Control Center.
· Site ID (only shown in Desktop for Web)
ID of the site this server belongs to. For more information on sites, refer to Chapter 3 – User Management – Managing Sites in the Administration Guide.
· Session guarantee / limit (Session guarantee only shown in Desktop for Web)
The number of guaranteed sessions available to this server and the concurrent session limit for this server. If no limit has been set, Not limited is shown. Note that the actual limit also depends on the limit set by the license key of the VoiceObjects installation.
The numbers shown in front are the granted guarantee and limit; the numbers shown in parentheses are the requested guarantee and limit.
· License expires
The expiration date for the license key of the VoiceObjects installation. Starting ten days before the expiration date, a yellow triangle icon 
is shown next to this entry (and to the right of the server name) to indicate that a new license needs to be acquired.
· Server version (only shown in Desktop for Eclipse)
Shows the build version of VoiceObjects Server.
· Tracing (only shown in Desktop for Eclipse)
Shows the status of the tracing, which is also indicated by the appropriate light in the Tracing column in the Control Center.
· Utterance recording (only shown in Desktop for Web)
Indicates whether utterance recording is enabled or disabled for this server.
· Errors (only shown in Desktop for Eclipse)
If an error occurred a corresponding message, explaining the problem, is shown here.
· Details (only shown in Desktop for Eclipse)
Shows the session statistics for the server. These figures are identical with those shown in the corresponding columns of the Server Manager tab.
Server Instance Management
This paragraph describes the server instance statistics shown in the nine additional columns of the Server Manager tab, all commands available in the server instance context menu, and the info box for the server instance details providing a summary of various server instance information.
Server instance statistics
To the right of the Server column, the next set of six columns provides session statistics for the server, displaying:
· Start Time
Indicating the time the server instance has been started.
· Active
Number of currently active sessions on this server instance.
· Finished
Number of sessions on this server instance that were completed successfully.
· Aborted
Number of sessions on this server instance that were aborted due to an error condition (including dialog timeout).
· Rejected
Number of sessions on this server instance that were rejected. This may happen because the corresponding service was not started when the session came in, or because no matching service could be found for the VSN and/or DNIS provided. It may also happen when no more concurrent sessions are available for a certain service, server, or the entire VoiceObjects installation.
· Total
Sum of the previous four columns.
The following two columns, System DB Logging and Custom DB Logging, indicate the currently applicable DB logging options for the server instance as enabled (green light ), disabled (red light ), unavailable (yellow light ), or not licensed (grey light ).
DB logging requires a valid license for Infostore.
i8 Note: While the red or green light indicates a specific administrator setting, the yellow light indicates that the respective logging option should be enabled, but failed due to a database connection problem. In order to resolve this, the respective server instance needs to be fully restarted (including its JVM) once database connectivity has been restored.
The grey light indicates that the license key for the server does not allow DB logging. Contact VoiceObjects regarding a license for Infostore.
The final column Tracing is empty as this setting is not available on sever instances, but only on servers and services.
In Desktop for Web the last three columns System DB Logging, Custom DB Logging and Tracing are not provided. Instead, two Memory columns are displayed, showing the used and free memory for the Java Virtual Machine (JVM) in which the server instance runs.
i8 Note: Depending on the JVM that is used, the amounts of memory shown here may differ from those configured in the start scripts for VoiceObjects Server.
Server instance context menu
To access server instance control functions, right-click anywhere in the row of the corresponding server instance entry. In Desktop for Web click the Context Menu button to the right of the server instance name. The following list describes the server control functions that are available from the context menu. Note that most of them are only available to Server Administrators or Server Controllers. Other user roles only see a subset of the functions. For more information on user roles and their privileges refer to Chapter 2 – User Management – Basic Topics in the Administration Guide.
The following server instance control functions are available from the context menu:
· Idle
Idles this instance. A warning window will appear to indicate that the instance will be idled. This does not affect currently active sessions, which are allowed to finish normally. If you confirm by clicking OK, the instance attempts to idle and the Control Center shows the “Please wait” icon. When the instance reaches idled state (after all active sessions on the instance have terminated), the instance’s status light changes to solid yellow.
This command is only available when the server instance is started.
If a media platform request comes into an idled server instance, it is automatically redirected to a started instance within the same cluster (as long as such an instance exists). This redirection uses the standard HTTP redirection mechanism.
· Resume
Resumes this instance.
This command is only available when the server instance is idled.
· Stop
Stops this instance. A warning window will appear to indicate that all currently active sessions on this instance will be terminated immediately. If you confirm by clicking OK, all currently active sessions on the instance are terminated, and the instance stops.
When an instance stops, all active and restore caches remain intact. When you start the instance again using the Start command, these caches are restored.
If a media platform request comes into a stopped server instance, it is automatically redirected to a started instance within the same cluster (as long as such an instance exists). This redirection uses the standard HTTP 302 mechanism.
· Start
Starts this instance.
This command is only available when the server instance is stopped.
When starting a stopped instance, all active and restore caches are restored from their previously persisted state, and application definitions are not reloaded from scratch. This ensures that the instance starts up again in the exact same configuration in which it was stopped.
· Details (only available in Desktop for Eclipse)
Opens up the Server Details with the Instance tab in front showing a summary of server instance information. In Desktop for Web the info box is opened by clicking the Maximize button at the right end of the row. Refer to Server instance details below for more details about the information displayed.
· Refresh (only available in Desktop for Eclipse)
Used to manually refresh the Control Center to display the currently active service states, call statistics, etc. In Desktop for Web the Refresh button in the menu bar can be used instead.
· Reports (only available in Desktop for Eclipse)
Provides a cascading submenu of reports available for the server instance. For details, refer to Appendix B – Control Center Reports.
This command is only available if Infostore is enabled for the server instance.
Server instance details
The info box for the server instance details can be opened by double-clicking the server instance entry on the Server Manager tab or by selecting Details from its context menu.
In Desktop for Web the info box is opened by clicking the Maximize button at the right end of the row.
The Server Details info box opens up showing the Instance tab in front.
For each available server instance a corresponding section is shown on the Instance tab, providing a summary of the following information about the server instance:
· System DB Logging
Indicates whether System DB logging is enabled or disabled for this server instance. Note that even when System DB logging is enabled for the server, DB connection problems or other issues may lead to situations in which it cannot be activated for certain server instances.
· Custom DB Logging
Indicates whether Custom DB logging is enabled or disabled for this server instance. Note that even when Custom DB logging is enabled for the server, DB connection problems or other issues may lead to situations in which it cannot be activated for certain server instances.
· Used memory (only shown in Desktop for Eclipse)
Shows the used memory for the Java Virtual Machine (JVM) in which the server instance runs.
· Free memory (only shown in Desktop for Eclipse)
Shows the free memory for the Java Virtual Machine (JVM) in which the server instance runs.
· Configured IP address
The IP address and port as defined in the configuration file for this server instance.
· Detected IP address
The IP address as detected by the server instance itself.
· Cluster Group
The cluster group this server instance belongs to.
· Errors
Shows any errors that may have occurred on this server instance, such as e.g. DB connectivity problems. If any errors have occurred, this is indicated by a yellow triangle icon to the right of the server instance name.
· Details (only shown in Desktop for Eclipse)
Shows the session statistics for the server instance. These figures are identical with those shown in the corresponding columns of the Server Manager tab.
Service Manager
The Service Manager section displays the list of services hosted on the server, together with their current status and session statistics. Services are identified by their VoiceObjects Service Name (VSN).
In Desktop for Web this information can be found in the Service Manager section of the Server Management tab.
The Service column shows the logical name of the service, which corresponds to the VSN of the Service object.
The Source column to the right of the Service column shows whether this service contains a start object from a project version (Project), a start object from a VoiceObjectsXML file (File), or is deployed from string (String).
For a detailed description of the remaining nine columns to the right refer to service statistics below. All available service commands are described in the service context menu paragraph and additionally the Service details paragraph gives an summary of various service information shown in the service info box.
At the top of the list of services hosted on this server, there is an entry “Invalid requests”. It serves to display session statistics for requests directed to non-existing or broken services, and for requests that could not be associated with any service. This may happen if the request did not indicate any service either by VSN or by DNIS. Such invalid requests may only lead to aborted or rejected sessions.
In Desktop for Web, services deployed directly from an XDK file are indicated by the file icon 
next to the VSN. For more information, refer to the XDK Guide.
Volatile services, i.e. services deployed directly from a string, are indicated by the string icon 
next to the VSN. For more information, refer to the redeployXDKApplication() method in Chapter 3 – Using the Web Services Interface (Deploy from string) and in Chapter 4 – Command Reference both in the Web Services Guide.
The service status is indicated by a traffic light symbol:
Icon |
Service Status |
|
|
Started. |
|
|
Idled. |
|
|
Stopped. |
|
|
Disabled. |
Services can transition from one status to another as outlined in the following diagram.
Next to the status, the service startup mode is indicated by an icon:
Startup mode is Automatic
Upon starting the server, the service definition is loaded and the service is started automatically. This is the default for new services.
Startup mode is Manual
Upon starting the server, the service definition is loaded, but the service is not started automatically.
Startup mode is Disabled
Upon starting the server, the service definition is not loaded.
The startup mode icons may also occur with an additional red dot (
,
,
) to indicate that the option Retain caches on shutdown is active on the respective service.
Knowing the startup mode is useful to quickly check whether all hosted services start up in their desired configuration when starting a server.
If a problem occurs during the loading of a service definition, a yellow triangle icon is displayed to the right of the VoiceObjects Service Name. The tool tip for this icon describes the problem in more detail. The exact error message can also be found in the info box for the service.
i8 Note: A stopped service cannot be started if it shows the yellow triangle icon . It must first be redeployed to a valid application definition.
If the media platform tries to access a service that is idled or stopped, a failover VoiceXML file using the settings defined in the corresponding service (language, media platform driver, etc.) is returned.
If the media platform tries to access a service that does not exist or is disabled, a failover VoiceXML file using the default settings of the server is returned.
In either case, the appropriate VoiceXML file is dynamically generated based on configurations defined in the files SystemFailovers.xml and SystemFailoverTexts.xml in the folder ..\VoiceObjects\Platform\WEB-INF\config.
It is possible to provide a static alternative file instead in the following location:
..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\<VoiceXML version>\<Media Platform Provider>\<ProductVersion>\
Unavailable.vxml
The file may contain custom VoiceXML or other markup code appropriate for the respective media platform. In this way, custom behavior can be achieved for failover cases.
A simpler variation is to just modify the audio played within the failover VoiceXML. To modify it, the audio file
..\VoiceObjects\Platform\Resources\System\Audio\<LanguageCode>\
service_unavailable_formal.wav
can be replaced by a custom recording.
If a request for a new dialog session cannot be granted due to an insufficient number of available concurrent sessions, separate failover files are played depending on the configured Reject response. They are also dynamically generated or can be provided at
..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\<VoiceXML version>\<Media Platform Provider>\<ProductVersion>\Overflow.vxml
and
..\VoiceObjects\Platform\Resources\System\VXML\<LanguageCode>\dialogs\VXML\<VoiceXML version>\<Media Platform Provider>\<ProductVersion>\Redirect.vxml
As above, it is also possible to modify the audio file
..\VoiceObjects\Platform\Resources\System\Audio\<LanguageCode>\
service_overflow_formal.wav
Service statistics
The next set of columns on the Service Manager tab provides session statistics for this service, displaying:
· Start Time
Date and time the service was most recently started or redeployed.
· Active
Number of currently active sessions for this service.
· Finished
Number of sessions for this service that were completed successfully.
· Aborted
Number of sessions for this service that were aborted due to an error condition (including dialog timeout).
· Rejected
Number of sessions for this service that were rejected because the service was not started when the session came in, or because no more concurrent dialog sessions were available.
· Total
Sum of the previous four columns.
The following two columns, System DB Logging and Custom DB Logging, indicate the currently applicable database logging options for the service as enabled (green light ), disabled (red light ), or overridden (black light ). If Infostore filtering is used, the icon will be partly red and partly green depending on the selected coverage.
The final column Tracing indicates whether tracing is currently enabled (green light or yellow light ), disabled (red light ), or overridden (black light ) for this service.
More details on the logging and tracing functionalities of VoiceObjects can be found in Chapter 5 - Logging and Tracing.
Service context menu
To access service control functions, right-click anywhere in the row of the corresponding service entry. In Desktop for Web click the Context Menu button to the right of the service name. The following list describes the available service control functions:
· Edit
Opens up the Service editor. Note that this entry is only available if the Service object comes from the Metadata Repository to which Desktop for Eclipse is currently connected. In addition the user account used for both the connections needs to be the same.
· Reload Service List (only available in Desktop for Eclipse)
Reloads the list of services hosted on this server. This is used when you have added a new service to a server, or removed a service from a server.
After reloading the service list, the Control Center will display any newly added services as stopped (see description of service states below). You need to start the service before it can be called.
Services that have been deleted from the server will only be removed from the Control Center if they have been stopped before reloading the service list.
· Redeploy
Deploys an updated version of this service.
A warning window will appear to indicate that the service will be updated to the latest dialog definition. This does not affect currently active sessions, which are allowed to finish using the current dialog definition. If you confirm by clicking OK, a “Please wait” message comes up while the service is being redeployed. Depending on the size of the dialog definition, this process may take some time to complete.
If there are active sessions on the service when it is being redeployed, the Control Center will introduce an additional row for the service (a “shadow service”), displayed directly below the original service entry in orange.
This row summarizes all active sessions that still use previous dialog definitions. Once all of these active sessions have terminated, the row is removed and the session statistics are consolidated into the normal row for the service.
When redeploying a service, its tracing and logging settings are maintained.
If the updated cache cannot be loaded due to an error condition such as an invalid object definition in the application, the built-in safeguard mechanism keeps the currently active cache intact. The error condition is indicated by a yellow triangle icon to the right of the VoiceObjects Service Name, and the full error message is provided both as the tool tip for this icon, and in the service info box (see below). After having corrected the problem, redeploy again to activate the new cache. The warning icon will then disappear.
· Restore
Reverts back to the previously stored version of the application definition.
A warning window will appear to indicate that the service will be restored to its status prior to the most recent redeploy. This does not affect currently active sessions, which are allowed to finish using the current dialog definition. If you confirm by clicking OK, a “Please wait” message comes up while the service is being restored.
If there are active sessions on the service when it is being restored, the Control Center will introduce an additional row for the service, displayed directly below the original service entry in orange.
The Restore command is only available after a previous Redeploy.
· Idle
Sets this service into idled status.
This command is only available if the service is started.
A warning window will appear to indicate that the service will be idled. This does not affect currently active sessions, which are allowed to finish normally. If you confirm by clicking OK, the service attempts to idle and the Control Center shows the “Please wait” icon. When the service reaches idled state (after all active sessions on the service have terminated), the service’s status light changes to solid yellow.
· Resume
Resumes this service.
This command is only available if the service is idled.
· Start
Starts this service.
This command is only available if the service is stopped.
When a service is started, it attempts to claim any guaranteed sessions assigned to it. For more information, see Chapter 9 – Service Level Agreements (SLA).
i8Note: It may not be possible to start a service if the yellow triangle icon is displayed to the right of the VoiceObjects Service Name. In such cases, check the error description shown in the service info box (see below), correct the issue, and then redeploy the service. If the warning icon disappears, you can then start the service.
· Stop
Stops this service.
This command is only available if the service is started or idled.
A warning window will appear to indicate that all currently active sessions on this service will be terminated immediately. If you confirm by clicking OK, all currently active sessions on this service are terminated, and the service stops.
When a service is stopped, it releases all guaranteed sessions assigned to it. For more information, see Chapter 9 – Service Level Agreements (SLA).
· DB Logging Options
Used to modify the currently applicable options for System and Custom DB logging.
In the cascading submenu that comes up, both System DB logging and Custom DB logging can be enabled or disabled by clicking the respective entry. Changes made here have immediate effect, but they do not change the permanent settings made in the Service object. They influence the service behavior while the server that hosts the service is running. After a restart of the server, or a redeploy of the service itself, the service behavior reverts to what is defined in the Service object definition itself.
Note that the logging options settings made on the server level override those made on the service level. Thus, if System or Custom DB logging is disabled on the server level, it is automatically disabled for all services. This is indicated by the black light () in the respective DB Logging column of the Service Manager section.
· Tracing Options
Used to modify the currently applicable tracing options for the service.
In the window that comes up you can enable or disable tracing, as well as define a comma-separated list of ANIs for which to trace sessions. No wildcards (such as ? or *) are allowed in this list.
Enabling tracing with an empty ANI list means that all sessions will be traced. This is strongly discouraged in a production deployment, as it negatively impacts performance. Tracing is reset to Disabled when restarting the server that hosts the respective service. Tracing settings are kept intact during a service redeploy.
For a more detailed description of the tracing functionality refer to Chapter 5 – Logging and Tracing.
When tracing is enabled for a service, this is indicated by a green light () in the respective Tracing column on the Service Manager tab. If tracing is restricted to a certain list of ANIs, this is indicated by a yellow light ().
Note that the tracing options settings made on the server level override those made on the service level. Thus, if tracing is disabled on the server level, it is automatically disabled for all services. This is indicated by a black light ().
· Debug Viewer
Starts a Debug Viewer session for this service. For further information refer to Debug Viewer in Chapter 4 –Service Deployment.
This command is only available if the service is started.
· Phone Simulator
Starts a Phone Simulator session for this service.
From the cascading submenu that comes up, you can select to start the Phone Simulator in the text or Web channel.
For further information refer to Phone Simulator in Chapter 4 –Service Deployment.
· Details (only available in Desktop for Eclipse)
Opens up the Service Details showing a summary of service information. In Desktop for Web the info box is opened by clicking the Maximize button at the right end of the row. Refer to Service details below for more details about the information displayed.
· Refresh (only available in Desktop for Eclipse)
Used to manually refresh the Control Center to display the currently active service states, call statistics, etc. In Desktop for Web the Refresh button in the menu bar can be used instead.
· Properties (only available in Desktop for Web)
Opens up the Properties window for this service.
· Reports (only available in Desktop for Eclipse)
Provides a cascading submenu of reports available for the service. For details, refer to Appendix B – Control Center Reports.
This command is only available if Infostore is enabled for the service.
Service details
The Service Details info box can be opened by double-clicking the service entry on the Service Manager tab or by selecting Details from its context menu.
In Desktop for Web the info box is opened by clicking the Maximize button at the right end of the row.
For each available service a corresponding section is shown, providing a summary of the following information about the service:
· Service object
Name of the Service object for this service.
· Project
Name of the project in which the start object can be found.
For XDK services deployed from a file or for volatile services, the project is shown as Unavailable. Refer to the XDK Guide for more information.
· Project version
Name of the project version in which the start object can be found.
For XDK services deployed from a file or for volatile services, the project version is shown as Unavailable. Refer to the XDK Guide for more information.
· Start object
Name of the start object defined for the service.
For XDK services, the start object may be a URL. Refer to the XDK Guide for more information.
For volatile services, the start object is only the reference ID of the start object itself. For more information, refer to the redeployXDKApplication() method in Chapter 3 – Using the Web Services Interface (Deploy from string) and in Chapter 4 – Command Reference both in the Web Services Guide.
· Site ID
ID of the site the service belongs to. For more information on sites, refer to Chapter 3 – User Management – Managing Sites in the Administration Guide.
· Utterance recording (only shown in Desktop for Web)
Indicates whether utterance recording is enabled or disabled for this service. Note that this setting may be overridden by the one on server level.
· System DB Logging (only shown in Desktop for Eclipse)
Indicates whether System DB logging is enabled or disabled for this service. Note that even when System DB logging is enabled for the server, DB connection problems or other issues may lead to situations in which it cannot be activated for a certain service.
· Custom DB Logging (only shown in Desktop for Eclipse)
Indicates whether Custom DB logging is enabled or disabled for this server instance. Note that even when Custom DB logging is enabled for the server, DB connection problems or other issues may lead to situations in which it cannot be activated for a certain service.
· Infostore filtering (only shown in Desktop for Eclipse)
Shows the current coverage of the Infostore logging as selected in the Service object.
· Active cache timestamp
Time when the currently active cache was created. If no active cache is available, this is shown as Unavailable.
· Active cache size
Size of the currently active cache.
For reference purposes, the internal cache ID is also provided.
· Restore cache timestamp
Time when the current restore cache was created. If no restore cache is available, this is shown as Unavailable.
· Restore cache size
Size of the current restore cache.
For reference purposes, the internal cache ID is also provided.
· Session guarantee / limit (Session limit only shown in Desktop for Web)
The number of guaranteed sessions available to this service and the concurrent session limit for this service. If no limit has been set, Not limited is shown.
The numbers shown in front are the granted guarantee and limit; the numbers shown in parentheses are the requested guarantee and limit.
A yellow triangle icon at the end of this entry indicates that either the session guarantee or the session limit was overridden. The tool tip for the icon provides details.
· Session distribution
The session distribution percentage defined for this service, or Disabled if none is defined.
A yellow triangle icon at the end of this entry indicates that the session distribution is ignored.
· Tracing (only shown in Desktop for Eclipse)
Shows the status of the tracing, which is also indicated by the appropriate light in the Tracing column in the Control Center.
· Filter scope (only shown in Desktop for Eclipse)
Shows the filter scope of the Infostore logging as selected in the Service object. This can either be Input State, System DB or System and Custom DB.
· Errors
Shows any errors that may have occurred during the most recent (re-) deployment of this service. If errors have occurred, a yellow triangle icon is shown to the right of the VoiceObjects Service Name.
· Details (only shown in Desktop for Eclipse)
Shows the session statistics for the service. These figures are identical with those shown in the corresponding columns of the Service Manager tab.
When running a server in a cluster configuration, each new server instance synchronizes with the current state of the instances in the portion of the cluster that is already running.
Upon starting the first server instance in a cluster, its hosted services come up as configured in the corresponding Service objects, i.e. they come up as started if their mode is set to Automatic and they come up as stopped if their mode is set to Manual (assuming there are no problems during startup; see Configuring a Service in Chapter 2 – Configuring Servers and Services for details). Manual changes can then be made to their states via the Control Center or the Command Line Interface.
As a new instance in the server cluster for the respective server is started, it restores the previously determined application cache and status. As all changes to the cluster configuration are persisted to the database and restored from there, the entire cluster is always maintained in a consistent state.
8 Caution: When a service needs to be completely removed from a server, make sure that the service is first stopped. If there are active sessions, this should be done by first idling the service, waiting until all active sessions have finished, and then stopping it so as not to interrupt the ongoing sessions. Then remove the respective Service object from the list of hosted services in the Server object. Finally, use the Reload Service list command discussed above to synchronize the state of the server with its definition.
Maintenance Operations
In a production deployment, it becomes necessary from time to time to perform certain maintenance operations such as swapping a hard drive, adding memory, etc. This paragraph describes how to perform such actions on a VoiceObjects installation without creating downtime. Of course this is only possible when using a cluster setup with multiple machines. For details on cluster configuration refer to Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide.
In addition to possible cluster operations it is strongly recommended to regularly perform maintenance operations on the used database system in order to secure best performance. See the paragraph on Database Maintenance for details.
Take a machine out of a cluster
To perform maintenance on a machine, it typically needs to be shut down. To do this gracefully without impacting call sessions, proceed as follows:
1. Idle all server instances on the machine.
2. Reconfigure the load balancer that assigns requests coming from the media platform to server instances such that the machine that is to be taken down does not receive new requests.
3. Wait until all active dialog sessions on any server instance on this machine have finished.
4. Stop all server instances on the machine.
5. Shut down the machine.
Note that while the server instances are idled (after the first step), new sessions that are routed to any of these instances by the load balancer will automatically be redirected to other active server instances within the cluster. This ensures that during the intermediate time until the second step has been completed, all incoming sessions are answered and handled correctly.
Bring a machine back into a cluster
After having completed maintenance work on a machine taken out of the cluster as described above, the machine needs to be brought back into the cluster. To do so, simply start the respective server instances on the machine. They will automatically merge back into the cluster and start the same services as all other instances within the cluster.
After all server instances on the machine have started successfully, reconfigure the load balancer that assigns requests coming from the media platform to server instances such that the machine is included again.
Add a new machine to a cluster
As an installation may grow with more call traffic on existing applications or the addition of new applications, an existing cluster configuration sometime needs to be extended by adding more hardware. Adding a new machine to an existing cluster should be done as follows:
1. Configure the new machine as described in Chapter 1 – Advanced Configuration of VoiceObjects in the Administration Guide. Make sure that the list of cluster members contains all existing machines as well as the new one.
2. Start all server instances on the new machine.
3. Reconfigure the load balancer that assigns requests coming from the media platform to server instances such that the new machine is included.
4. For each of the “old” machines in the cluster, follow the steps described above to take it down. Then adjust its cluster configuration to include the new machine, and bring it back into the cluster.
5. After the previous step has been performed for all “old” machines in the cluster, the new cluster is set up and contains all machines, including the newly added one.
Change the VSN of a service
In rare case, it becomes necessary to change the VoiceObjects Service Name (VSN) of a deployed service. Note that this is an operation that requires changes on both the VoiceObjects and the media platform side.
To gracefully change the VSN, follow these steps (assuming that the service is currently started):
1. In the Service object, change the VSN to the new value and save the object.
2. Reload the service list on the server. This adds the service with its new VSN, in stopped state. Note that the service is also still present with its old VSN.
3. Start the service with the new VSN.
4. Once the service is started, adjust the media platform configuration such that requests now use the new VSN instead of the old one.
5. Wait until all existing calls on the service with its old VSN are completed. Then stop the service.
6. Reload the service list on the server once again. This removes the stopped service with the old VSN.
Cluster split-up
If there are problems in the network such as outages of switches or routers or network cables that accidentally get unplugged, a cluster of VoiceObjects Server instances may temporarily break up into smaller sub-clusters. When network connectivity is restored, the cluster usually merges back together within a matter of minutes.
While the cluster is split up, the following guidelines should be followed:
· Do not take any special actions to manually merge the cluster. It will merge back automatically. This process can take anywhere from a few seconds to a couple of minutes, counting from the time that network connectivity is restored between all members of the cluster.
· Do not perform any Control Center operations (such as starting, stopping, or redeploying services) while the cluster is split. If you do, the cluster state will become inconsistent and operations may have strange effects after the cluster merges back together.
· Avoid starting up or bringing down instances while the cluster is split.
· The Control Center may block temporarily while the cluster is split. The CLI may block or return error messages.
· In isolated cases it might be required to bring down and restart an instance if it fails to reappear in the Control Center.
· In isolated cases it might be required to close the Control Center tab and open it again if it continues to show an empty list of instances.
Database maintenance
The following steps are important in order to maintain optimal database performance:
Regular statistics update
To improve the performance it is necessary to regularly run the statistics scripts MDStatistics.sql and LDStatistics.sql located at:
<VoiceObjects_HOME>\Platform\WEB-INF\driver\db\<DBMS>
Typically, this is done by using a batch job.
Regular deletion of logging data
The amount of data that is logged by Infostore to the database can significantly grow over time especially in large installations with high call volumes. Depending on the available resources and business requirements it might be necessary to establish a process that removes old logging data from the database.
Typically, this is done by using a batch job.