Java Management Extensions (JMX) is a Java technology specifically designed for managing Java applications. It is part of the standard Java Virtual Machine and defines a standard interface for clients and servers. An application that to be managed by JMX will register MBeans to the JMX context. An MBean can be used to expose information about the system that an administrator can fetch (for example, the total simultaneous calls on the system). An MBean can also be used to expose a function that an administrator can execute (for example, to suspend an application). A client application communicates with the server through the JMX interface to allow administrators access to the information and function that is exposed.

VXML Server, is a server application, exposes many informational MBeans for information regarding itself as well as the applications deployed on it. It also exposes administrative MBeans for controlling important administrator functions. It does this in a fully JMX-complaint manner so that any JMX-compatible client will be able to interface with VXML Server to gain access to the information and functions. One such client is JConsole, which is a client bundled with JDKs provided by Sun Microsystems and others. Some JVMs and application servers provided by other companies may utilize alternative JMX-compatible clients that should work as well.

It is also possible for a developer to create their own custom MBeans for exposing functions or information that will then be viewed by a JMX-compatible client alongside the MBeans exposed by VXML Server. See the Programming Guide for Cisco Unified CVP VXML Server and Cisco Unified Call Studio for more on creating custom MBeans.

VXML Server is configured to be JMX enabled when using Tomcat. The JMX port number by default is 9696.

Once VXML Server is started, a JMX client can then be launched and configured to point to the machine on which VXML Server runs, whether it be on the same machine or a remote one. Once connected, the client provides a graphical interface for displaying the information and functions. The client will be able to display information about the JVM itself and typically the Java application server will publish its own set of MBeans. VXML Server information will be displayed where the MBeans are listed in its own domain. The domain is typically rendered in a tree structure and will list global information and functions (that is, information having to do with VXML Server itself) as well as information on the deployed voice applications. Detailed explanations of the individual MBeans are provided in the following sections.

To address security, JMX client consoles require the proper security certificates (if JMX security is enabled on the VXML server) and the client attempts to connect to a remote server. Certificates are not required to connect to a local VXML Server because the client already has access to the local system. For details on securing communication and accessing secured communications, see the Configuring and Modifying Unified CVP Security section in Configuration and Administration Guide for Cisco Unified Customer Voice Portal.

Of the available administration interfaces, the JMX interface for VXML Server provides the greatest functionality and flexibility. It does, however, require the JVM to have JMX active and a JMX-compatible client. It also has a higher risk and overhead due to this flexibility.

Most of the administration functions and some of the information about VXML Server are provided via command-line scripts that can be executed by an administrator manually or an automated system directly. The administrator scripts do not use the JMX interface described in the previous section and are functional by default without requiring any configuration on the administrator’s part. The included scripts act as the client. The scripts are provided in two forms: batch scripts for Microsoft Windows (ending in .bat) and shell scripts for Unix (ending in .sh).

Scripts are provided to execute global functions (on VXML Server itself) or functions for individual applications. The scripts used for global administrator functions are found in the admin directory of VXML Server. The scripts used for individual application administration are located in the admin directory of each application.

The provided scripts are primarily used to expose VXML Server functions to administrators such as loading a new application, updating an existing application, suspending VXML Server, and so on. Some scripts provide information, such as the number of active simultaneous calls on the server. This chapter describes in detail all available scripts and their functionality.

Security is an important concern when it comes to administration functions that are accessed from the command-line. Unified CVP sets up these precautions to allow only the appropriate people access to these scripts:

• By providing scripts or batch files (as opposed to through a graphical or web interface), the administrator must be logged into the machine in order to access them. Accessing these programs is as secure as the remote login process (such as SSH) and the permissions given to these scripts or the entire admin folder.

• VXML Server will only accept commands from the local machine, so even scripts stored on one machine cannot issue commands to an instance of VXML Server running on another machine. These two precautions ensure that only authorized administrators can access these functions.

Because the global administration scripts are stored in a different location from application scripts, each directory can be assigned different permissions. That way an administrator can be given access to the global administration scripts while still allowing the application scripts to be accessed by voice application developers.

Every administration script can be configured to ask for confirmation before the action is taken, to prevent the accidental execution of the script. By default the confirmations are on. They can be turned off by passing the command-line argument noconfirm to the script. This action can be useful if the administration scripts are executed by automated systems such as cron jobs.

While not as flexible as the JMX interface, administration scripts provide easy access to VXML Server functions for both administrators and automated systems out of the box. The risk potential is similar to that of the JXM interface although there is less overhead because JMX is not enabled.

The system information page provides basic information about VXML Server including the license information, the deployed gateway adapters and applications, the status of information on the application server on which VXML Server is running, and some miscellaneous system and Java information such as the version and memory usage. It does not provide the ability to execute any functions, it is meant to be a quick way to check relevant information. It is also the easiest of the three methods to obtain information because all that is needed is a web browser. The system information page can be seen by pointing a web browser to the URL:

http://[HOST][:PORT]/CVP/Info

Where:

• HOST is the host name of the machine on which VXML Server is installed.

• PORT is the port the application server is configured to listen on. The default port for HTTP is 7000.

The first time you access the server information page you must configure a username and password. After you create the username and password you can log in and view the page.

The system information page is the easiest and safest way of obtaining administrative information, although it is also the least flexible.

VXML Server provides functions for reporting the status of a specific voice application or all voice applications running on the system. They are provided as functions to allow the administrator to query VXML Server to get the latest information immediately.

The application status function reports the following information:

• Whether the application is running, suspended, or has been suspended before being slated for removal.

• How many active sessions are currently visiting the application. Active sessions are defined as the number of callers that are interacting with the application at the time the status script is called.

• How many sessions are waiting to end. When an active caller ends their application visit, VXML Server delays the closing of the corresponding session to allow the completion of the session accessed by the final logger and end of call class actions. A session waiting to end does not take up a license port. The amount of time a session remains open after a call ends is a VXML Server configuration option (see VXML Server Configuration for more).

• How many open sessions are experiencing the most recent past version of the application. Open sessions are the sum of active callers visiting the application and those sessions that are in the process of ending. The reason open sessions are listed here is because both active and ending sessions do need access to session information and an administrator would need to know when it is safe to disable any systems that the old application configuration depends on. This information is helpful for an administrator when performing an application update or suspension in order to determining when the executed function is complete. See the following sections for more on updating and suspending applications.

• How many callers are on hold waiting to get into the application. A call that is received when the system has used up all the allowed sessions defined in the license will hear a message asking them to stay on the line. This call then checks if a license session has become available and then lets the call into the application.

The VXML Server status function provides an easy-to-read report with the following information:

• If VXML Server itself has been suspended, this fact is listed first. See the following sections for more on suspending VXML Server.

• The total number of concurrent active callers visiting applications on this instance of VXML Server, how many concurrent sessions the license allows, the number of available ports (the license sessions minus the active callers), and the number of callers on hold (which would only appear if the number of current callers exceeds the number of license sessions).

  Note	This data is not available in case of a standalone deployment.

• How many active callers, sessions ending, and callers on hold for each application currently deployed on the system. This data is the same as would be displayed by the application-specific status function.

  Note	No on hold column will appear unless there are callers on hold.

• Whether each application is running or suspended.

JMX Interface

To get an application’s status using the JMX interface, use a JMX client connected to the server to navigate to the VoiceApplication/APPNAME/Command MBean, where APPNAME is the name of the application to update. The Operations tab of this MBean will list a function named status. Pressing Status button will display a dialog box with the application status. To get the status of all applications using the JMX interface, navigate to the Global/Command MBean and click the function named status in the Operations tab. Pressing Status button will display a dialog box with the status of each application deployed on VXML Server in a table.

Administration Scripts

The script for obtaining an application status is found in the admin folder of the application to be updated. Windows users should use the script named status.bat and Unix users should use the script named status.sh. The script for obtaining the status of all applications is found in the admin folder of VXML Server. Windows users should use the script named status.bat and Unix users should use the script named status.sh. The scripts do not take any parameters.

VXML Server reports information about itself that is static so the administrator knows exactly what is installed. The following information is reported:

• The exact name and version of VXML Server.

• The expiration date, number of ports, and the supported gateway adapters listed in the VXML Server license.

  Note	The gateway adapter list is not a comprehensive list of the adapters installed on VXML Server but is a list of the gateway adapters the license allows the system to use.

• A detail of the version numbers of all components included with VXML Server. This information can be helpful for tracking changes made to individual components of the software installed at different times and this detailed information will typically be requested by Cisco support representatives when a question is raised about the software.

  The components whose versions are displayed are:

  • The VXML Server web application archive (WAR) and the components residing within %CVP_HOME%\VXMLServer\.

    Note	This version is different from the VXML Server product version as that is a version for the whole system and this one is only for the WAR file.

  • The core VXML Server elements, Say It Smart plug-ins, and loggers (both application and global) included with the software.

  • The Gateway Adapters installed on the system.

JMX Interface

To obtain VXML Server information using the JMX interface, navigate to the Info MBean. The attributes tab displays all the information listed. To see all the gateway adapters supported in the license, you must open the value for the LicensedGWAdapters attribute (in JConsole this is done by double-clicking the value). The same procedure applies for obtaining the component versions by opening the value for the ComponentVersions attribute.

Administration Scripts

The only VXML Server information available by using a script is the versions of the components installed on VXML Server, though the name and version of VXML Server is displayed when it initializes and the license ports is always displayed using the global status script.

The script is found in the admin folder of VXML Server. Windows users should use the script named getVersions.bat and Unix users should use the script named getVersions.sh. In order to report on the version of the VXML Server web application archive (WAR), the script should be passed as an argument the full path of the WAR location (for example, %CVP_HOME%\VXMLServer\Tomcat\webapps\).

System Information Page

The same information is displayed in the system information page at the top of the table. It will also provide a list of the applications deployed on VXML Server as well as information on the application server, operating system, and Java memory usage.

Server Status Checks

Many load balancers can be configured to periodically access a URL that is used to determine if a server is running. These load balancers make a request to the URL, and if a response comes back within an acceptable time period, they consider the server available to handle connections. To determine the health of VXML Server, include the parameter probe=true in the request URL, using one of the following formats:

  http://[DOMAIN][:PORT]/CVP/Server?probe=true

OR:

  http://[DOMAIN][:PORT]/CVP/Server?application=[APPLICATION]&probe=true

The first URL format (without the application parameter) results in a simple HTML page with the following text if the VXML Server is accessible and is not suspended:

The Cisco Unified CVP VXML Server is up and running

However, if it is suspended (using the suspendServer administrative script), it will respond with:

  The Cisco Unified CVP VXML Server is running, however it has been suspended.

This URL format has several optional parameters that may be used in conjunction with it:

•   activeCalls=true

  This optional parameter causes the response HTML to include information about how many call sessions are active on the VXML Server instance. This is formatted as illustrated in the following example:

       running;activeCalls=12;

•   onHoldCalls=true

  This optional parameter causes the response HTML to include information about how many call sessions are in an on hold status on the VXML Server instance. This is formatted as illustrated in the following example:

       running;onHoldCalls=3;

•   activeCalls=true&onHoldCalls=true

  Specifying both of the optional parameters results in both data items being returned, as illustrated in the following example:

       running;activeCalls=77;onHoldCalls=0;

The second URL format (with the application parameter), results in a VoiceXML page which includes a <submit> to the listed voice application. If that VoiceXML page is returned, then VXML Server is accessible. This format is intended for use with load balancers that require the probe URL to match the URL through which actual content is retrieved. This format cannot be used to obtain additional information (that is, active and on-hold calls).

To view the configuration options of an application using the JMX interface, navigate to the VoiceApplication/APPNAME/Command MBean, where APPNAME is the name of the application. There are four attributes listed:

• DefautAudioPath - Shows the audio path defining where the audio files are located (assuming the application was designed to take advantage of it).

• GatewayAdapter - Shows the gateway adapter that the application is using and is not editable. It is for informational purposes only.

• SessionTimeout - Shows the length of time, in seconds, of inactivity to consider a call session timed out.

• SuspendedAudioFile - The path for the audio file to play to callers when calling into an application that is suspended.

An administrator may choose to change the default audio path of an application at runtime should there be a need to change the audio callers hear quickly. One use case would be if the server that hosts the audio files is being restarted and the administrator wishes all audio to be fetched from a backup server.

Note	The effectiveness of this change will be based on how consistently the application was designed to use the default audio path and also if the application explicitly sets the default audio path itself, which would override the value passed here.

An administrator may choose to change the session timeout value at runtime as part of the process of debugging a problem. Under normal circumstances no session should time out because the voice browser and VXML Server should be in constant communication regarding when a call starts and ends. An administrator experiencing some sessions timing out may choose to increase this attribute to see if it resolves the issue and if not, should look into network issues. The administrator should be careful not to set this value too small a number because there is a risk that a normal call could time out due to the caller visiting a particularly large VoiceXML page or taking their time entering a long DTMF input. Too large a number will mean that sessions that are no longer valid will remain in memory longer and the administrator would not be able to see which sessions are timed out until the timeout period elapsed.

An administrator may choose to change the suspended audio file at runtime if the application needed to be suspended due to a specific reason. For example, if a weather event required an application to be suspended, the administrator could point the suspended audio message to a recording explaining why the application is suspended rather then just pointing to a generic message. The administrator is taking advantage of the fact that this change is not persisted since it is expected that the event that caused the application’s suspension is temporary.

Administration functions are used primarily to alter an application, whether it be to update its contents or suspend its activity. Whenever changes are made to a live system handling callers, a concern is how these changes affect live callers. A robust, reliable system should strive for maximum uptime and minimal disruptions of live calls, and VXML Server does this by implementing a process for managing changes.

In the process, existing callers continue to experience the application as it existed before the change, while new callers experience the change. Only after all existing callers have naturally ended their calls will the change apply to all live callers. At this time, VXML Server will perform any necessary cleanup required to remove the old application configuration. In this manner, changes can be made to applications at any time; the administrator does not need to worry about the impact of the change on live callers as the transition will be handled.

Due to the interactive nature, when using administration scripts to perform graceful functions, the script will display a count down of callers that are actively visiting the application as they end their calls. This is provided because an aid to the administrator in determining how many callers are still experiencing the application before the change. Command-line arguments passed to the scripts can turn off this countdown if desired.

When using the JMX interface or if the countdown is turned off in the administration script, the only way to track the number of callers that are still experiencing the old configuration would be to get the system status.

Occasionally, an application will need to be updated. Possible changes can be small, such as renaming an audio file or altering a TTS phrase, or large, such as adding another item to a menu and creating a new call flow branch. They can involve simple configuration changes or may involve new or changed Java class files. While most changes are implemented during development time, there is a requirement to support updating an application at runtime.

The update functionality acts gracefully in that any callers on the system, at the time of update continue to experience their calls as if the application had not been updated, while new callers experience the updated voice application. In this manner, there is no downtime when a change is implemented for an application, the callers are handled as expected.

VXML Server exposes an update function for every application deployed. This Server will update only that application. It also has a function that updates all applications at once.

When updating individual voice applications note these guidelines:

• The update applies only to those resources controlled by VXML Server. These include the application settings and call flow, element configurations, Unified CVP decision elements, and Java classes placed in the java/application directory of the application. The following changes are not managed by VXML Server and therefore will not be updated:

  • Java classes placed anywhere else (including the common folder).

  • XML content passed to VXML Server by using the XML API.

  • The content of VoiceXML insert elements.

  • Other applications that the updated application transfers to or visits as part of a subroutine.

  • External back-end systems such as web services and databases (including the user management database).

  • Web servers hosting static content used by the application such as audio or grammar files.

  When each of these resources become unavailable or change, all callers would be affected. For small changes such as a revised audio file, this situation may be acceptable. For large-scale changes that span multiple systems, this might cause problems such as callers who are visiting an application when the update is made experiencing an error because a database is down.

  For large changes, the application should be suspended and the changes made once all callers have left the system (see the following section on suspending applications). Once the application is fully suspended, the administrator is free to make the changes and when done, the application should be updated followed by resuming it from its suspended state. This way, no caller will be in the system when the changes are made. The only disadvantage to this approach is that it will make the application unavailable for a period of time as opposed to a transparent change if the update feature alone is used. This may be a necessary compromise considering the consequences.

• When the update occurs, the event created by VXML Server to send to any loggers that are listening will reflect when the update function was executed, not when it completed.

• If an error occurs during the update process, for example, due to an incorrectly configured XML file, a description of the error is displayed and sent to any loggers listening to the appropriate logger events and the update is cancelled.

• If an updated VXML server application is transferred from OAMP to VXML Servers while calls are in progress, the following message appears in the log:

  %CVP_8_5_VXML-3-VXML_INTERNAL_ERROR:DatafeedMgr.handleActEvent() java.lang.NullPointerException]

  Note	In this case, calls are not disconnected, but the related VXML events during the update will not be sent to the reporting server.

JMX Interface

To update an application using the JMX interface, use a JMX client connected to the server to navigate to the VoiceApplication/<APPNAME>/Command MBean, where APPNAME is the name of the application to update. The Operations tab of this MBean will list a function named updateApplication. Pressing updateApplication button will cause the application to be updated and the result of the update will be displayed in a dialog box.

The administrator should be aware that there is no confirmation when this function is called, the update happens immediately once executed.

Note

While the function returns immediately, the old application may still be active if there were calls visiting the application at the time of the update. Only when all existing callers end will the old application configuration be removed from memory. To determine when that occurs, use the status function.

To update all applications at once using the JMX interface, navigate to the Global/Command MBean and click the function named updateAllApps in the operations tab. The results are displayed in a dialog box, listing each application updated. As with the application-specific update, use the status function to determine if there are callers experiencing old versions of the applications.

Administration Scripts

The scripts for updating an application are found in the admin folder of the application to be updated. Windows users should use the script named updateApp.bat and Unix users should use the script named updateApp.sh.

The script will first ask for confirmation of the desired action to prevent accidental execution. To turn off the confirmation, pass the parameter noconfirm. By default, the script does not return to the command prompt until all pre-update callers are finished. Interrupting the countdown will not stop the update process, only the visual countdown. To turn off the countdown, pass the parameter nocountdown. If the countdown is interrupted or the script is passed with the nocountdown parameter then the only way to determine how many callers are experiencing the old application is to execute the status script for the system, which displays this information.

The script to update all applications is found in the admin folder of VXML Server. Windows users should use the script named updateAllApps.bat and Unix users should use the script named updateAllApps.sh. The script behavior is the same as if the update script for each application deployed on VXML Server were executed in series.

The updateAllApps script also displays a confirmation prompt, which can be turned off by passing the noconfirm parameter. Unlike the updateApp script, the updateAllApps script does not display a countdown of callers, it lists all the applications that are updated. The administrator would need to execute the status function to determine how many callers are visiting the old versions of the applications.

There are many situations when an application needs to be temporarily suspended. There could be scheduled maintenance to the network, the voice application could have an expiration date (say it runs a contest that must end at a specific time), or the application is to be turned off while enterprise-wide improvements are made. There may also be situations where all applications are to be put in suspension if modifications are being made that affect all applications. In each of these situations, a caller would need to be played a designer-specified message indicating that the application has been temporarily suspended, followed by a hang-up. This is preferable to not answering or taking down the system, which would cause a cryptic outage message to be played.

First, the application designer defines the suspended message in the Application Settings pane in Builder for Call Studio. When the suspend order is given, VXML Server produces a VoiceXML page containing this suspended audio message to all new calls followed by a hang-up. Because VXML Server allows all calls currently on the system to finish normally when the command was issued, existing callers are unaware of any changes. VXML Server will keep track of the active callers visiting the application and make that information available for the administrator to access. Only when this number reaches 0 will it be safe for the administrator to perform the system maintenance that required the suspension.

VXML Server exposes suspend and resume functions for every application deployed that acts on just that particular application. It also exposes a function that will suspend VXML Server itself, which has the effect of suspending all applications. A separate resume function resumes VXML Server that restores the previous state of each application. So if an application was already suspended when VXML Server was suspended, resuming VXML Server leaves the application in a suspended state.

There are a few items to note when suspending a voice application:

• Only when all existing callers have exited the system will the application be officially suspended. Depending on the average length of calls to the voice application, this may take some time. The application status will appear as suspended since new callers cannot enter the application, and they will hear the suspended audio message.

• If changes were made to an application while it was suspended, the application should first be updated before being resumed (see the previous section on the update administration function).

• The suspension applies only to those resources under the control of VXML Server. External resources such as databases, other web servers hosting audio or grammar files, or servers hosting components through XML documents over HTTP are accessed at runtime by VXML Server. If any of these resources become unavailable while there are still presuspension callers on the system, those calls will encounter errors that will interrupt their sessions. Any maintenance made to backend systems should be initiated after the application status shows that all presuspended callers are finished with their calls.

• When the suspension occurs, the event created by VXML Server to send to any loggers that are listening will reflect when the suspend function was executed, not when it completed.

• If an error occurs during suspension, a description of the error is displayed and sent to any loggers listening to the appropriate logger events and the update is cancelled.

• Suspending a voice application still requires VXML Server (and the Java application server) to be running in order to produce the VoiceXML page containing the suspended message. If the application server itself requires a restart, there are four possible ways to continue to play the suspended message to callers. Remember to execute the suspend function before any of these actions are taken as this is the prerequisite.

  The solutions are listed in order of effectiveness and desirability:

  • Load balance multiple instances of VXML Server—In a load-balanced environment, one machine can be shut down, restarted, or reconfigured while the rest continue serving new calls. Once removed from the load-balance cluster, a machine will not receive new call requests. Eventually, all existing callers will complete their sessions, leaving no calls on the machine removed from the cluster. That machine can then be safely taken down without affecting new or existing callers.

  • Use a web server as a proxy—In a smaller environment, a web server can be used as a proxy for an application server so that when that application server becomes unreachable, the web server itself can return a static VoiceXML page containing the suspended message to the voice browser. The web server does not need to be on the same machine as the application server. Once the web server is configured, VXML Server can be suspended to locate all existing callers, then the application server can be taken down and the proxy server will take over producing the suspended message VoiceXML page. The disadvantage of this approach is that the web server setup is done outside of Unified CVP and if the suspended message changes, it needs to be changed in both the Builder for Call Studio and the web server configuration.

  • Redirect the voice browser—The voice browser can be configured to point to another URL for calls coming on the specific number. This can point to another machine running VXML Server or even just a web server with a single static VoiceXML document playing the suspended message. A separate file would be needed for each application. This is a manual process and requires another machine with at least a web server (it can be on the same machine which would allow the Java application server to be restarted but would not allow the machine itself to be restarted).

JMX Interface

To suspend an application using the JMX interface, use a JMX client connected to the server to navigate to the VoiceApplication/APPNAME/Command MBean, where APPNAME is the name of the application to be suspended. The Operations tab of this MBean will list a function named suspendApplication. Pressing suspendApplication button causes the application to be suspended and the result is displayed in a dialog box. To resume the application, select the function named resumeApplication. The result is displayed in a dialog box.

The administrator should be aware that there is no confirmation when these functions are called, the suspension and resumption occurs immediately once executed.

Note

While the suspend function returns immediately, the application may still be active if there were calls visiting the application at the time of the suspension. Only when all existing callers end their calls will the application be fully suspended and the administrator is safe to take down any resources that the application depends on. To determine when all calls have ended, use the status function.

To suspend VXML Server itself using the JMX interface, navigate to the Global/Command MBean and click the function named suspendVXMLServer in the operations tab. The results will be displayed in a dialog box. As with the application-specific suspension, use the application-specific status function to determine if there are callers still visiting the applications. Click the function named resumeVXMLServer to resume VXML Server and restore the previous states of the applications.

Administration Scripts

The scripts for suspending and resuming applications are found in the admin folder of the application to be suspended. Windows users should use the script named suspendApp.bat and Unix users should use the script named suspendApp.sh. To resume the application, use the script named resumeApp.bat or resumeApp.sh.

It is possible to suspend all applications at once by accessing a script found in the admin folder of VXML Server. Windows users should use the script named suspendServer.bat and Unix users should use the script named suspendServer.sh. To restore all applications to their original status, use the script named resumeServer.bat or resumeServer.sh.

Note	These scripts do not resume all applications; they only restore the administrator-specified status of each application. So if an application was already suspended when the server was suspended, resuming the server leaves the application in a suspended state.

When VXML Server starts up, it will load all applications that have been deployed to its applications folder. A new application that is created in Builder for Call Studio and deployed to a machine on which VXML Server is already running cannot begin accepting calls until VXML Server loads the new application. To load the application, execute the deploy application function. If the application is already deployed, executing this function will do nothing. If multiple new applications are to be deployed together, one can execute the deploy all applications function and all new applications will be deployed, and leave existing applications untouched.

JMX Interface

To deploy all new applications using the JMX interface, use a JMX client connected to the server to navigate to the Global/Command MBean and click the function named deployAllNewApps in the Operations tab. Pressing deployAllNewApps button displays a dialog box with the status of each application’s deployment.

Alternatively, to deploy a single new application, first use the function named listAllNewApps in the operations tab to get a list of new application names. Then use the deployNewApp function to deploy the desired application by name.

Administration Scripts

The script for deploying a specific application is found in the admin folder of the application to be deployed. Windows users should use the script named deployApp.bat and Unix users should use the script named deployApp.sh. The script for deploying all new applications at once is found in the admin folder of VXML Server. Windows users should use the script named deployAllNewApps.bat and Unix users should use the script named deployAllNewApps.sh.

VXML Server demonstrate two administrative functions to handle the removal of application from memory at runtime. Determining which function to use will depend on the operating system and whether the application being removed is actively handling calls.

The first method involves executing the release application function of the application to be removed. This function prompts VXML Server to first suspend the application then remove it from memory when all the active callers at the time the function was executed, have naturally ended their sessions. It suspends the application first to prevent new callers from entering the application. Once all active callers are done visiting the application the folder of the application can be deleted (or moved) from the VXML Server applications folder. This function affects only a single application so if multiple applications are to be removed using this method, the administrator would have to execute this function for each application.

Note

On the Microsoft Windows operating system, a user attempting to delete an application folder after the releaseApp function is called may be prevented from doing so by the operating system if the application references Java application archive (JAR) files placed within the java/application/lib or java/util/lib directories. This is due to the system keeping an open file handle for JAR files that will not be released until a garbage collection event occurs. As a result, the administrator will have to wait until the garbage collector activates before being able to delete the directory. The time to wait will be determined by how often garbage collection is run. A rule of thumb is that a high load system or one with a small amount of memory will encounter garbage collection often, a low volume system or one with a large amount of memory will take longer.

The second method supports the ability to delete multiple applications at once. This time one must first delete (or move) the folders holding the desired applications to be deleted. After which, the flushing of all old applications function is executed and VXML Server will suspend and then remove from memory of all the applications that it no longer finds in the applications folder. As with the other method, the application is not removed from memory until all callers have ended their visits.

These issues can occur with the second method:

• If an application relies on files found within its folder at runtime, there may be problems with existing callers reaching a point where these files are needed and they will not be found.

• This process may not work on Microsoft Windows because Windows will not allow the deletion of a folder when resources within it are open. For example, the application loggers may have open log files located within the application’s logs folder. This may work if no loggers are used or the only loggers used are those that do not manage files stored in the logs folder.

JMX Interface

To delete an application using the JMX interface, use a JMX client connected to the server to navigate to the VoiceApplication/<APPNAME>/Command MBean, where APPNAME is the name of the application to update. The Operations tab of this MBean will list a function named releaseApplication. Pressing releaseApplication button will cause the application to be suspended and then removed from memory when all active callers visiting the application at the time the function was executed have completed.

The administrator should be aware that there is no confirmation when this function is called; the application is suspended and removed from memory immediately once executed.

Note

While the function returns immediately, the application will remain active if there were calls visiting the application at the time of the release. Only when all existing callers end, the call will the application be removed from memory. To determine if there are active callers, use the status function.

To delete all applications whose folders have been removed from the applications folder of VXML Server using the JMX interface, navigate to the Global/Command MBean and click the function named releaseAllOldApps in the operations tab. The results will be displayed in a dialog box, listing each application deleted. As with the application-specific update, use the status function to determine when the callers finish their visits to the applications.

Administration Scripts

The scripts for deleting an application are found in the admin folder of the application to be updated. Windows users should use the script named releaseApp.bat and Unix users should use the script named releaseApp.sh.

The script first asks for confirmation of the desired action to prevent accidental execution. To turn off the confirmation, pass the parameter noconfirm. By default, the script does not return to the command prompt until all callers are finished with their calls. Interrupting the countdown will not stop the release process. To turn off the countdown, pass the parameter nocountdown. If the countdown is interrupted or the script is passed the nocountdown parameter, then the only way to determine how many callers are actively in the application is to execute the status script for the system.

The script to release all applications whose folders have been removed from the applications folder of VXML Server is found in the admin folder of VXML Server. Windows users should use the script named flushAllOldApps.bat and Unix users should use the script named flushAllOldApps.sh. All applications whose folders have been removed will be suspended and when their active calls have ended will be removed from memory.

The flushAllOldApps script also displays a confirmation menu which can be disabled by passing it the noconfirm parameter. Unlike the releaseApp script, the flushAllOldApps script does not display a countdown of active callers, it will list all the applications that were deleted. The administrator would need to execute the status function to determine how many callers are actively in the applications.

When performing an application update, all the data and Java classes related to an application will be reloaded. Java classes placed in the common folder of VXML Server are not included in the application update. VXML Server provides a separate administrative function to update the common folder.

There are a few items to note about this function:

• The update affects all applications that use classes in the common folder, so executing this function could affect applications that have not changed. Therefore, take precaution when executing this function.

• The update affects all classes in the common folder, whether they were changed or not. This is usually not a issue unless those classes contain information in them that reloading would reset (such as static variables).

• Due to the fact that this function reloads classes that affect all applications, and those classes may themselves prompt the loading of configuration files from each application that uses those classes, the function may take some time to complete depending on the number of classes in the common folder and the number and complexity of the deployed applications.

• Changes are immediate, and are not done. Because this potentially affects all applications, the administrator must be aware of this.

JMX Interface

To update common classes using the JMX interface, use a JMX client connected to the server to navigate to the Global/Command MBean and click the function named updateCommonClasses in the operations tab. The results will be displayed in a dialog box.

Administration Scripts

The script for updating common classes is found in the admin folder of VXML Server. Windows users should use the script named updateCommonClasses.bat and Unix users should use the script named updateCommonClasses.sh. The script will ask for confirmation of the desired action to prevent accidental execution. To disable the confirmation, pass the parameter noconfirm.

Global data holds information that applications decide to share across other applications deployed on VXML Server. Application data holds information that applications decide to share across all calls to the application. The VXML Server JMX interface provides the ability for an administrator to view the contents of these variables, change their values, and even create new variables.

This functionality provides an administrator direct access to live data that is being created on the system and can provide them some control of how applications operate. This is only possible when the application designers design that functionality into the applications. For example, an application designer for a utility company can build their application to look for the existence of a global data variable reporting a power outage. The administrator then creates the global data variable when a power outage occurs and automatically the applications will start reporting the power outage to callers. The administrator can then delete the global data variable to signify the power has been restored. While this same functionality could be achieved with a database, this is a simpler approach to handle predictable situations without the need to use a database.

Global Data Access

To access global data using the JMX interface, navigate to the Global/Data MBean. The Attributes tab lists all the global data variable names in an attribute named AllGlobalDataNames (the value may need to be expanded in order to see all the global data names). The Operations tab lists four functions that can be executed by the administrator for global data:

• setGlobalData—This function allows the administrator to create a new global data variable. The function requires the name of the variable and the value. Click setGlobalData button to set the global data and the result will appear in a dialog box.

  Note	If there exists global data with the same name it will be overridden.

• removeGlobalData—This function allows the administrator to delete a global data variable. The function takes one input: the name of the global data variable to delete. Click removeGlobalData button to remove the global data and the result will appear in the dialog box.

• removeAllGlobalData—This function allows the administrator to delete all global data, whether it was created by the administrator or applications. Click removeAllGlobalData button to remove all global data and the result will appear in the dialog box.

  Be careful when using this function because it can affect the performance of applications that rely on global data.

• getGlobalData—This function allows the administrator to retrieve the value of a global data variable. The function takes one input: the name of the global data variable to retrieve. Click getGlobalData button to display a dialog box showing the value of the global data.

Application Data Access

To access application data using the JMX interface, navigate to the VoiceApplication/APPNAME/Data MBean, where APPNAME is the name of the application whose application data is to be accessed. The Attributes tab lists all the application data variable names in an attribute named AllApplicationDataNames (the value may need to be expanded in order to see all the application data names). The Operations tab lists four functions that can be executed by the administrator for application data:

• setApplicationData—This function allows the administrator to create a new application data variable. The function takes two inputs, the first being the name of the variable and the second being the value. Click setApplicationData button to set the application data and the result will appear in a dialog box.

  Note	If there is already application data with the same name it will be overridden.

• removeApplicationData—This function allows the administrator to delete a application data variable. The function takes one input: the name of the application data variable to delete. Click removeApplicationData button to remove the application data and the result will appear in the dialog box.

• removeAllApplicationData—This function allows the administrator to delete all application data, whether it was created by the administrator or applications. Click removeAllApplicationData button to remove all application data and the result will appear in the dialog box. Be careful with this function as it could affect the performance of the application.

• getApplicationData—This function allows the administrator to retrieve the value of a application data variable. The function takes one input: the name of the application data variable to retrieve. Click getApplicationData button to display a dialog box with the value of the application data.

VXML Server includes various default loggers, including administration history loggers that store a history of the administration activity taken, such as when VXML Server started up, when an application was updated, the results of the suspension of VXML Server, and so on. These logs, which are rotated daily, are useful to an administrator as an audit history of administrator activity. As a convenience, the JMX interface exposes methods for the administrator to access the contents of these logs instead of viewing the files in a text editor.

Note

The application designer and administrator has the ability to define any loggers desired for the applications as well as for VXML Server, including removal of the default administration history loggers. If this is done, then these functions will return error messages that explain that the log files could not be found.

To view an application’s administration history log using the JMX interface, use a JMX client connected to the server to navigate to the VoiceApplication/<APPNAME>/Command MBean, where APPNAME is the name of the application to view. The Operations tab of this MBean lists functions named retreiveAdminHistoryToday and retreiveAdminHistoryAll. Clicking the first opens up a scrollable window listing the contents of the administration history log file from the day the function is called. Clicking the second opens up a scrollable window listing the contents of all administration history logs concatenated.

To view VXML Server administration history log using the JMX interface, navigate to the Global/Command MBean. The operations tab of this MBean list functions with the same name and functionality as the application functions do except that the files accessed are for the global administration history.