Article ID:	171
Last updated:	January 12, 2007

Would you like to...

Print this page

Post a comment

User Opinions

No users have voted.

---

How would you rate this answer?

Helpful

Not helpful

Thank you for rating this answer.

SUMMARY

This article describes each of the administrative features of Audium Call Services in detail.

SYMPTOMS

N/A

RESOLUTION

Call Services provides several mechanisms to perform maintenance while minimizing any detrimental effects on callers. These functions are designed to allow an administrator to make both small and large changes to one or more applications while Call Services is still handling callers. They are divided into two categories: those that affect a specific application and those that affect all applications running on Call Services.

The user performs these administrative functions by running shell scripts (.sh) on Linux/Solaris or batch files (.bat) on Windows. The scripts used for individual application administration are located in the admin directory of each application. The scripts used for global administrator functions are found in the admin directory of Call Services.

Each administrator function updates a log file specifically used to track administrator activities. This file exists for audit purposes. The administrator can use the log to determine when certain actions took place or how long certain conditions existed.

Security

Security is an important concern when it comes to administration functions that can affect one or all voice applications. There are several precautions Audium sets up to allow only the appropriate people access to these scripts. First, by providing scripts or batch files (as opposed to through a graphical or web interface), the administrator must be logged into a machine in order to access them. Therefore, 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. Secondly, Call Services will only accept commands from the local machine, so even scripts stored on one machine cannot issue commands to a Call Services instance running on another machine. These two precautions ensure that only authorized administrators can access these functions.

Since 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.

Finally, 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 can be useful if the administration scripts are run by automated systems like cron jobs.

Graceful Administration Functions

Administration scripts 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 Audium Call Services does this by implementing a "graceful" process for managing changes.

In the graceful 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, Call Services will perform any necessary cleanup required to remove the old application configurations. In this manner, changes can be made to applications at any time, the administrator need not worry about the impact of the change on live callers as they will be handled gracefully.

When a graceful administration script is executed, it will keep track of callers that were already visiting the application and display a count down as those callers naturally end their calls. This is provided as 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. The information on the number of callers visiting the old and new versions of the application is still available when obtaining the status of the system.

The description of the various administration functions listed below will each explain the manner in which their actions are handled gracefully (if applicable) and any points that need to be considered when the administration script is run.

Updating Applications

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. These kinds of changes occur most frequently when the voice application is being developed, and less frequently on a live application.

The update functionality acts gracefully in that any callers on the system at update time continue to experience the rest of the call 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 needed for an application, the callers are handled as expected.

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 Linux/Solaris users should use the script named updateApp.sh. It is possible to update all applications deployed on Call Services: Windows users should run the script named updateAllApps.bat and Linux/Solaris users should run the script named updateAllApps.sh found in the admin folder of Call Services. This script essentially runs the update script for each application deployed on Call Services.

There are a few items to note when updating individual voice applications.

• The script does not return to the command prompt until all pre-update callers are finished.
• The gracefulness of the update applies only to those resources controlled by Call Services. These include the application settings and call flow, element configurations, Audium decision elements, and Java classes placed in the java / application directory of the application. The following changes are not managed by Call Services and therefore will not be gracefully updated:

  • Java classes placed anywhere else (including the common folder in Call Services),

  • XML content passed to Call Services via the XML API.

  • The content of VoiceXML insert elements.

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

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

    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 could 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 tradeoff considering the consequences.

• When the update occurs, the administration log file will reflect when the update script was run, not when it completed.

• If an error occurs during the update process, e.g., due to an incorrectly configured XML file, a description of the error is displayed to the console window and stored in the admin log and the update is cancelled.

Suspending 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 simply 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 Audium Builder for Studio. When the suspend order is given, Call Services produces a VoiceXML page containing this suspended audio message to all new calls followed by a hang-up. Since Call Services gracefully allows all calls currently on the system to finish normally when the command was issued, existing callers are unaware of any changes. Once all the old calls are completed and all new callers are receiving the suspended audio message, Call Services reports the application as being successfully suspended for all callers. Only then is it safe for the administrator to perform the system maintenance that required callers to be prevented from entering the application.

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 Linux/Solaris 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 Call Services. Windows users should use the script named suspendServer.bat and Linux/Solaris 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 that this script does not resume all applications; it simply restores the administrator-specified status of each application. So if an application was already suspended when the suspendServer script was called, resumeServer leaves it 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.
• 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 Call Services. External resources such as databases, other web servers hosting audio or grammar files, or servers hosting components via XML documents over HTTP are accessed at runtime by Call Services. If any of these resources become unavailable while there are still pre-suspension 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 suspend script indicates that all pre-suspended callers are finished with their calls.
  
• When the suspension occurs, the administration log file will reflect when the suspend script was run, not when it completed.
  
• If an error occurs during suspension, a description of the error is displayed to the console window and stored in the admin log and the suspend order is cancelled.
  
• Suspending a voice application still requires Call Services (and hence 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 run the suspend script 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 Call Services instances. 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. Please refer to the Administrator Guide and the documentation for the load balancers being used to for more information.
  • 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 need not be on the same machine as the application server. Once the web server is configured, Call Services can be suspended to flush out 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 Audium and if the suspended message changes it would need to be changed in both the Audium Builder for 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 Call Services 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).
    

Adding Applications

A new application that is created in Audium Builder for Studio and deployed to a machine on which Call Services is running cannot begin accepting calls until Call Services loads the new application. In order to load the application, the deployApp script found in the admin folder of the new application should be launched. Windows users should use the script named deployApp.bat and Linux/Solaris users should use the script named deployApp.sh.

If multiple applications are created and need to be deployed together, the deployAllNewApps script found in the admin directory of Call Services will deploy all new applications together. Windows users should use the script named deployAllNewApps.bat and Linux/Solaris users should use the script named deployAllNewApps.sh. All existing voice applications are unaffected and calls can now be received for all new applications.

Note that due to the fact that Call Services automatically loads all available applications when the Java application server is started up, there is no need to run an administration script when new applications are deployed on Call Services while the application server is not running.

Removing Applications

There are two separate methods for removing an application from the memory of Call Services while the Java application server is still running. Determining which method to use will depend on the operating system and the circumstances behind the application removal.

The first method involves two steps. The first is to delete (or move) the folder holding the desired application from the Call Services applications folder. The second step involves launching the flushAllOldApps.sh (or flushAllOldApps.bat on Windows) script found in the Call Services admin folder to prompt Call Services to remove all applications whose folders have been removed from memory. The script itself first suspends the applications so that any new callers visiting them while they are being removed will hear the suspended application audio. Call Services will also act gracefully for the removal: all callers visiting the applications at the time they are being removed will continue to experience the applications unchanged.

While this is the simplest method, it does pose some issues. The first is that if an application relies on files found within its folder at call time, there may be problems with existing callers reaching a point where these files are needed and they will not be found. The second issue is that this process will not work on Windows since Call Services opens log files located within the application’s logs folder and the operating system will not allow the deletion of a folder when resources within it are open.

The second method for removing an application from Call Services addresses these issues. The first step would be to run the releaseApp.sh (or releaseApp.bat on Windows) script in the application’s admin folder. This prompts Call Services to first suspend the application then remove it from memory in the same way as the flushAllOldApps script does. At this point the application folder can be deleted (or moved). It is important to do this only after the releaseApp script has indicated that all existing callers to the application have left. Being an application-specific script, it affects only a single application, so if multiple applications are to be removed using this method, the administrator would have to run this script for each application. Once this process is complete, there is no need to use the flushAllOldApps script. While used primarily with Windows, this process works equally as well in Linux or Solaris.

Updating Common Classes

When performing an application update using the updateApp or updateAllApps scripts, all the data and Java classes related to an application will be reloaded. Java classes placed in the Call Services common folder are not included in this update. Should changes be made to classes in the common folder, Windows users should run the script named updateCommonClasses.bat and Linux/Solaris users should run the script named updateCommonClasses.sh found in the Call Services admin folder.

There are a few items to note about this script:

• The update affects all applications that use classes in the common folder, so running this script could affect applications that have not changed. Therefore, take precaution when running this script.
• 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 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 script 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, they are not done gracefully. Since this potentially affects all applications, the administrator must be aware of this.

Application and System Status

Call Services provides scripts named status.bat for Windows and status.sh for Linux/Solaris users for reporting the status of a specific voice application or all voice applications running on the system. The global status script is found in the admin folder of Call Services while the application-specific status script is found in the admin folder of that application.

The application status script reports the following information:

• How many callers are currently visiting the application and how many are on hold waiting to get into the application.
• Whether the application is running, suspended, or has been suspended before being slated for removal.
• How many of the current callers are experiencing an old version of the application and how many are experiencing the newest version of the application. This information would be useful if the administrator interrupted the updateApp script while it was counting down the number of callers still experiencing the old application version.

The global status script reports the following information:

• The total number of callers visiting this instance of Call Services, how many license ports the system possesses, and the number of callers on hold (which would only appear if the number of current callers exceeds the number of license ports).
• How many callers are currently visiting each application deployed on the system and how many are on hold waiting to get into each application.
• Whether each application is running or suspended.

Audium Component Versions

Call Services provides a script that reports the version of all the components of the software, including Call Services, the core Audium element package, and each Gateway Adapter installed on the system. This information can be helpful for tracking changes made to individual components of the software installed at different times and the output of the script will typically be requested by Audium support representatives when a question is raised about the software.

The script is found in the admin folder Call Services. Windows users should use the script named getVersions.bat and Linux/Solaris users should use the script named getVersions.sh. The script requires as an argument the full path of the location in which the Audium web application was installed (e.g. "C:\Program Files\Apache Group\Tomcat 4.0\webapps\").

Administration Script Reference

The following lists all the scripts found in the admin folders of an individual application as well as for Call Services itself.