How to Start the Command Line Interface (CLI)

The Control Center Command Line Interface (CLI) is a component of VoiceObjects that enables the deployment and monitoring of servers and services from a terminal console.

The steps required to start the Control Center CLI depend on the operating system.

Windows

To start the Control Center CLI on Windows, open a command line window by running cmd.exe. Navigate to the VoiceObjects installation folder (using the cd command). From there, navigate to the Platform\WEB-INF\bin directory. Execute CLI_ControlCenter.bat to start the Control Center CLI.

Linux / Unix

To start the Control Center CLI on Linux, open a shell. Change the current working directory to the VoiceObjects installation directory. Go to the bin directory below the WEB-INF directory. Call the CLI_ControlCenter.sh shell script to start the Control Center CLI.

Commands

When calling the Control Center CLI without any parameters, help for the various available commands is displayed.

 

Each command is listed in the help page together with required arguments and a description. For some commands and parameters, a single letter version is available.

All commands require the following parameters:

·          host (-h): The name under which the machine, which is currently the master in the cluster, is reachable within the network. In non-clustered installations this is the name of the machine. If you specify the host of a server instance that is not currently the master server manager, you are automatically redirected.

·          port (-p): The port on which VoiceObjects Server is running. This port is defined by the setting instancePort within the configuration file VOServer_Configuration.xml. If you specify the port of a server instance that is not currently the master server manager, you are automatically redirected.

·          ccURL: Instead of specifying the host and port information, this parameter can be used to directly define a WSDL URL to connect to a logical server. Typically it is of the form: http://myServer:myPort/VoiceObjects/Services/WSProvider?wsdl

·          certificateURL (-C): Specifies the path to a SSL certificate, which is used for authentication if the Control Center URL defined above uses an HTTPS connection. The path can either be defined by using the HTTP or file protocol.

·          aggregate: By default set to true, in this case the data for services is aggregated on server level. To retrieve the service information per server instance this has to be set to false.

·          user (-u): The username that should be used for this connection. To work with the Control Center CLI, you need to have a user role with access to the Control Center. The information displayed in the CLI is filtered in the same way as that displayed in the Control Center. For more information, refer to Chapter 2 – User Management – Basic Topics in the Administration Guide.

·          password (-w): The password used for user authentication.

·          passwordURL (-U): Specifies the path to a file containing a password, which is used for authentication if the password parameter should not be used e.g. due to security reasons. The path can either be defined by using the HTTP or file protocol.

·          server (-x): The name of the logical server. This name is identical with the reference ID of the Server object.

To avoid having to confirm a warning by typing “y”, the parameter -forceExecution can be specified. In this case the command execution is forced without displaying a warning and the option to cancel the command. This parameter is usually helpful in batch scripts.

As an alternative to the pretty-printed console output shown below, it is also possible to retrieve the information in an XML format by providing the parameter -xml. The XML output format is described in the section XML Output Format.

Server

To retrieve the current status of a server or access the server control functions, choose one of the following commands:

·          queryServer (-q): Displays the status of the specified server. The status display includes the names or IP addresses and ports of the available server instances, the used and free memory of the servers and the start time of each server. In addition, information on the status of Custom and System DB logging, as well as tracing is shown. The server instance running as master instance is also indicated with a [M] suffix.
The Service Manager section shows the available services by VSN, the status of the services, the start time and the number of active, finished, aborted and rejected sessions. In addition, information on the status of Custom and System DB logging, as well as tracing is shown.
For more details on the call status see Chapter 3 – Managing Servers and Services.

The queryServer command should be used after any of the service commands described below has been issued in order to check whether the command was processed successfully.

·          reloadServiceList: Reloads the list of services hosted on the server. This command is used after adding a service to a server or removing services from a server.
After submitting this command the next query command will display any newly added services as stopped. Services will only be removed from the server if they were stopped before reloading the service list.

·          tracingServer: Used to activate or deactivate tracing functionality on the server. Possible values are on and off.
Note that if tracing is deactivated on the level of the server, this overrides all settings made on the service level.

·          dbLoggingServer: Used to configure the active DB logging options for the server. Possible values are none, custom, system, and both.
none switches off both Custom and System DB logging.
custom enables only Custom DB logging.
system enables only System DB logging.
both enables both Custom and System DB logging.
Note that if Custom or System DB logging is deactivated on the level of the server, this overrides all settings made on the service level.

·          startServer: Starts the 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.

·          idleServer: Idles the server. For a cluster this means that all individual started server instances in the cluster are idled. A warning message will appear to indicate that the server will be idled. This does not affect currently active sessions, which are allowed to complete normally. If you confirm by typing “y”, the server is idled.
This command is only available when the server is started.

·          resumeServer: Resumes the server. For a cluster this means that all individual server instances (both idled and stopped ones) in the cluster are started.
This command is only available when the server is idled. When resuming an idled server, all idled services are also resumed.

·          stopServer: Stops the server. For a cluster this means that all individual server instances in the cluster are stopped. A warning message will appear to indicate that all currently active sessions will be terminated immediately. If you confirm by typing “y”, 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 startServer command, these caches are restored.

·          resetServer: Resets the 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 message will appear to indicate that all currently active sessions will be terminated immediately. If you confirm by typing “y”, all currently active sessions are terminated, and the server resets. During reset, all services are stopped, their application caches are loaded, and the services are then started according to their startup mode settings.
This command is only available when the server is started or idled.

·          shutdownServer: Shuts down the server. For a cluster this means that all individual server instances in the cluster are shut down. A warning message will appear to indicate that all currently active sessions will be terminated immediately. If you confirm the shutdown by typing “y”, 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).

8     Caution: Once the server has been shut down, it cannot be started again from within the Control Center CLI. Instead, it needs to be started locally on the appropriate machine as described in the Installation Guide.

Typical examples for server commands are:

·          Querying the server “VOServer”
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –u voadmin –w manager –q

·          Querying the server “VOServer” without using the password parameter
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –u voadmin –U file://d:/temp/pass.txt –q

·          Resetting the server “Acme”
cli_controlcenter.bat –h apache –p 8099 –x Acme –u admin –w fedora -resetServer

·          Shutting down the server “Engine”
cli_controlcenter.bat –h host36 –p 8099 –x Engine –u sa –w sa -shutdownServer

Server instance

A server instance has to be referenced by its unique name:

·          instance (-z) : Specifies the name of the server instance as configured in the <instanceName> tag in the configuration file VOServer_Configuration.xml.
If no name is specified in the configuration file, use <instanceIP>:<instancePort> (e.g. 192.168.0.1:8099) to identify the server instance you want to invoke a command on.
Note that the instance name needs to be unique within the cluster.

To control individual server instances, add one of the following commands:

·          startInstance: Starts the instance.
This command is only available when the server instance is stopped. Note that 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.

·          idleInstance: Idles the instance. A warning message will appear to indicate that the instance will be idled. This does not affect currently active sessions, which are allowed to complete normally. If you confirm typing “y”, the instance is idled.
This command is only available when the server instance is started.
If a media platform request comes into an idled or stopped server instance, it is automatically redirected to a started instance for the same logical server within the same cluster (as long as such a started instance exists). This redirection uses the standard HTTP redirection mechanism.

·          resumeInstance: Resumes the instance.
This command is only available when the server instance is idled.

·          stopInstance: Stops the instance. A warning message will appear to indicate that all currently active sessions on this instance will be terminated immediately. If you confirm by typing “y”, 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 startInstance command, these caches are restored.

·          getErrorInstance: Retrieves error messages for the instance. This command is used if an error condition is indicated by the token ERROR in the instance’s status entry.

Typical examples for server instance commands are:

·          Idling the server instance “Dagobert” running on localhost, port 8099
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –z Dagobert –u voadmin –w manager -idleInstance

·          Stopping the server instance running on localhost, port 8099
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –z localhost:8099 –u voadmin –w manager -stopInstance

Service

The services hosted on a server can be controlled by the commands explained in the following.

·          service (-y) : Specifies the VoiceObjects Service Name (VSN) of the service to be controlled.

·          tracingService: Used to activate or deactivate tracing functionality on the service. Possible values are on and off.

·          restrictANI: Restricts tracing to a comma separated list of ANIs for this service. Double quotes must be used to comprise the ANIs, e.g. “ANI1,ANI2,…”

·          dbLoggingService: Used to configure the active DB logging options for the service. Possible values are none, custom, system, and both.

·          startService: Starts the service.
This command is only available if the service is stopped or idle.
The counter for rejected calls will be set back to 0.

·          redeployService (-r) : Deploys an updated version of the service. This command is available if the service is started, stopped or idled. A warning message will appear to indicate that the service will be updated to the latest service and dialog definition. This includes also refreshing the cache for this service. Existing sessions are not affected by redeploying the service. These sessions are completed using the current dialog definition. If the redeployment is confirmed by typing “y”, the service will be redeployed. Depending on the size of the application definition, this operation can take several minutes. Nonetheless, the Control Center CLI returns immediately.
If there are active sessions for the service that is being redeployed, a service with the suffix SHADOW will appear the next time the server is queried. After the last call that was dependent on the previous dialog definition has finished, the SHADOW service will be removed. Additionally all session counters are added to the currently active service.

·          restoreService: Reverts the service back to the previously stored version of the application definition.
A warning message 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 complete using the current dialog definition. If confirmed by typing “y”, the service is restored.
The restoreService command is only available after a previous redeployService.

·          idleService: Sets the service into the idle status. This command is only available if the service is started. A warning message will appear to indicate that the service will be idled. If the idling is confirmed by typing “y”, the service will be idled. This does not affect any active sessions, which are allowed to complete normally. All incoming new sessions to the service will be rejected.
All session counters are preserved.

·          resumeService: Resumes the service. This command is only available if the service is idled. After a successful resume the service is started and can again accept new sessions.

·          stopService: Stops the service. This command is only available if the service is started or idled. A warning message will appear to indicate that the service will be stopped. If the stopping is confirmed by typing “y”, the service will be stopped. Any active sessions will be terminated immediately.
All session counters are set back to 0.

·          getErrorService: Retrieves error messages for the service. This command is used if an error condition is indicated by the token ERROR in the service’s status entry.

Typical examples for service commands are:

·          Idling service “insurance”
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –y insurance –u voadmin –w manager -idleService

·          Redeploying service “banking”
cli_controlcenter.bat –h host36 –p 8099 –x Engine –y banking –u sa –w sa –r

XML Output Format

To allow an easy integration with system management frameworks, the output of CLI requests can be retrieved in an XML format, which can be automatically parsed and processed.

The XML output format provides the complete set of information shown in the Control Center of VoiceObjects Desktop, including the content of the info boxes for all servers and services. Due to formatting restrictions, this information is not shown in the normal CLI output.

The XML output can either be shown on the console by using the –xml command (see example 1 below) or be written to a file by using –xml together with the optional command –toFile [directory\filename]. If using the –toFile command the created file can be found either in the WEB-INF folder of your VoiceObjects installation (see example 2 below) or in the specified directory (see example 3 below).

Typical examples:

1          XML output to the console for queryServer command
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –u voadmin –w manager –queryServer -xml

2          XML output to a custom file for queryServer command
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –u voadmin –w manager –queryServer –xml –toFile file.txt

3          XML output to a custom file in c:\ for queryServer command
cli_controlcenter.bat –h localhost –p 8099 –x VOServer –u voadmin –w manager –queryServer –xml –toFile c:\file.txt

The XML output comes in two different flavors, one for the query command and one for all other commands. A schema representing the provided XML structure can be found in the file

[VoiceObjects installation]\Platform\WEB-INF\schemas\ VoiceObjectsCLIXMLOutput.xsd

Query result

The <root> element of the XML structure, lists the information about the server and its components in four different subelements:

<creationDetails>
<serverDetails>
<serverInstances>
<services>

<creationDetails>

Contains general information about the creation of this content.

XML Element	Description and Example
<user>	Name of the user who created this content, e.g. voadmin.
<timestamp>	Shows the timestamp when this content was created. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<serverVersion>	Version of VoiceObjects Server, e.g. 7.1.0.1250

 

<serverDetails>

Contains all information about the server itself.

XML Element	Description and Example
<referenceID>	Unique reference ID of this server e.g. VOServer.
<status>	Status of this server. Possible values are: STARTED STARTING STOPPED STOPPING IDLED IDLING
<startTime>	Start time of this server. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<activeSessions>	Shows the number of currently active sessions for this server.
<finishedSessions>	Shows the number of finished sessions for this server.
<abortedSessions>	Shows the number of aborted sessions for this server.
<rejectedSessions>	Shows the number of rejected sessions for this server.
<totalSessions>	Shows the total number of sessions for this server (addition of active, finished, aborted, and rejected sessions).
<tracing>	Status of tracing for this server. Possible values are: Enabled Disabled Unavailable
<systemDBLogging>	Status of System DB logging for this server. Possible values are: Enabled Disabled Unavailable Enabled / Not available Not licensed
<customDBLogging>	Status of Custom DB logging for this server. Possible values are: Enabled Disabled Unavailable Enabled / Not available Not licensed
<utteranceRecording>	Status of utterance recording for this server. Allowed values are: Enabled Disabled
<siteID>	Identifies the site this server belongs to. The site is identified either by an explicitly defined site ID or by the name of the root Site Administrator. If the server is from the system site System is returned.
<owner>	Shows the user ID of the user who created this server.
<locked>	Identifies the lock status of this server. Allowed values are: true false
<lockAccountID>	Shows the GUID of the user who locked this server.
<lockAccountName>	Shows the name of the user who locked this server.
<sessionLimit>	Shows the granted and requested session limit for this server. The string unlimited is used if the number of sessions is not limited, e.g. 300(400).
<sessionGuarantee>	Shows the granted and requested guaranteed number of sessions for this server. 0 indicates that no sessions are guaranteed for this server, e.g. 100(100).
<group>	Shows the group this server belongs to.
<licenseExpireDate>	Shows the date when the license for this VoiceObjects Server expires. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 2007-07-16T19:20+01:00.

 

<serverInstances>

Shows the list of existing server instances. Note that there can be various instances for one server, so there are N tags <serverInstance> that each contain all information about one specific server instance.

XML Element	Description and Example
<instanceName>	Shows the name for this instance. The name is defined in the configuration file VOServer_Configuration.xml.
<configuredIP>	Shows the internal IP address for this instance, e.g. 192.168.0.1. The internal IP address is defined in the configuration file VOServer_Configuration.xml.
<configuredPort>	Shows the port that is used by this instance, e.g. 8099. The port is defined in the configuration file VOServer_Configuration.xml.
<detectedIP>	Shows the detected IP address for this instance, e.g. 192.168.0.1
<master>	Identifies if this server instance is currently the master instance. Allowed values are: true false
<status>	Status of this instance. Possible values are: STARTED STARTING STOPPED STOPPING IDLED IDLING
<startTime>	Start time of this instance. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<activeSessions>	Shows the number of currently active sessions for this instance.
<finishedSessions>	Shows the number of finished sessions for this instance.
<abortedSessions>	Shows the number of aborted sessions for this instance.
<rejectedSessions>	Shows the number of rejected sessions for this instance.
<totalSessions>	Shows the total number of sessions for this instance (sum of active, finished, aborted and rejected sessions).
<usedMemoryMB>	Shows the size of the currently used memory in megabytes.
<freeMemoryMB>	Shows the size of the currently free memory in megabytes.
<error>	Lists error messages, e.g. Missing database connection for logging.
<infostoreErr>	Lists the System DB error messages for this server instance.
<customDBErr>	Lists the Custom DB error messages for this server instance.
<systemDBLogging>	Status of System DB logging for this instance. Possible values are: Enabled Disabled Unavailable Enabled / Not available Not licensed
<customDBLogging>	Status of Custom DB logging for this instance. Possible values are: Enabled Disabled Unavailable Enabled / Not available Not licensed

 

<services>

Shows the list of services hosted on this server. Note that there can be various services on one server, so there are N tags <service> that each contain all information about one specific service.

XML Element	Description and Example
<vsn>	Shows the VSN (VSN = VoiceObjects Service Name) of this service.
<name>	Shows the name of the Service object.
<source>	Used to identify if this service is deployed from file (file), deployed by string (string) or deployed by a service definition via VoiceObjects Desktop (project). Possible values are: project file string
<status>	Status of this service. Possible values are: STARTED STARTING STOPPED STOPPING IDLED IDLING UNAVAILABLE (only used for the Invalid Requests service) VALIDATING LOADING_CACHE
<startupMode>	Startup mode of this service. Possible values are: Automatic Manual Disabled
<startTime>	Start time of this service. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<activeSessions>	Shows the number of currently active sessions for this service.
<finishedSessions>	Shows the number of finished sessions for this service.
<abortedSessions>	Shows the number of aborted sessions for this service.
<rejectedSessions>	Shows the number of rejected sessions for this service.
<totalSessions>	Shows the total number of sessions for this service (sum of active, finished, aborted and rejected sessions).
<tracing>	Status of tracing for this service. Possible values are: Enabled Disabled Overridden
<traceANIs>	Shows a comma separated list of ANIs, e.g. +492204845196,+492204845197. Tracing will be restricted to these ANIs.
<systemDBLogging>	Status of System DB logging for this service. Possible values are: Enabled Disabled Overridden
<customDBLogging>	Status of Custom DB logging for this service. Possible values are: Enabled Disabled Overridden
<utteranceRecording>	Status of utterance recording for this service. Allowed values are: Enabled Disabled Overridden
<utteranceRecordingFiltering>	Show the utterance recording filtering for this service, e.g. a value of 15% means that for 15% of all logged sessions utterance recordings will be available.
<infostoreFiltering>	Shows the Infostore filtering for this service, e.g. 30% means that log data will be written for 30% of all sessions.
<filterScope>	Shows the filter scope for this service. Allowed values are: Input State SystemDB SystemDBCustomDB
<project>	Shows the name of the project this service belongs to, e.g. Prime Insurance. If the service is an XDK service, this is shown as Unavailable.
<projectVersion>	Shows the project version, e.g. 1.0. If the service is an XDK service, this is shown as Unavailable.
<startObject>	Shows the name of the start object for this service, e.g. PrimeInsurance Portal. If the service is an XDK service, this contains a URL pointing to the start object.
<error>	Lists error messages for this service e.g. Skipping configuration of service ‘PI’ due to missing start object.
<activeCacheTimestamp>	Timestamp of the currently used cache of this service. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<restoreCacheTimestamp>	Timestamp of the restorable cache of this service. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<activeCacheSizeKB>	Shows the size of the currently used cache for this service in kilobytes.
<restoreCacheSizeKB>	Shows the size of the restore cache for this service in kilobytes.
<siteID>	Identifies the site this service belongs to. The site is identified either by an explicitly defined site ID or by the name of the root Site Administrator. If the service is from the system site System is returned.
<locked>	Identifies the lock status of this service. Allowed values are: true false
<lockAccountID>	Shows the GUID of the user who locked this service.
<lockAccountName>	Shows the name of the user who locked this service.
<sessionLimit>	Shows the granted and requested session limit for this service. The string unlimited is used if the number of sessions is not limited, e.g. 200(unlimited).
<sessionGuarantee>	Shows the granted and requested guaranteed number of sessions for this service. 0 indicates that no sessions are guaranteed for this service, e.g. 200(400).
<sessionDistribution>	Shows the distribution of sessions over different services, e.g. 0.3 means that 30% off all available sessions are assigned to this service. Note that the sum of the percentages over all services on a server must not exceed 100% and that it can only be defined for all services on a server or for none.

Command result

The <root> element of the XML structure lists the information about command processing in two different elements:

<creationDetails>
<commandDetails>

<creationDetails>

Includes general information about the creation of this content.

XML Element	Description and Example
<user>	Name of the user who created this content, e.g. voadmin.
<timestamp>	Shows the timestamp when this content was created. This information is stored following the ISO 8601 format YYYY-MM-DDThh:mmTZD, e.g. 1997-07-16T19:20+01:00.
<serverVersion>	Version of VoiceObjects Server, e.g. 7.1.0.1250

 

<commandDetails>

Includes general information about the command processing.

XML Element	Description and Example
<command>	Shows the command, e.g. stopServer.
<executionResult>	Shows the execution result. Possible values are: 1 (indicates that an error occurred during processing) 0 (indicates that the command was processed successfully)
<message>	Shows the message that was produced by the server. This can either be a specific error message or the known message from CLI that asks you to check the status page.

And includes information about occurred errors and warnings.

XML Element	Description and Example
<errorCode>	Shows an internal error code, -1 is shown if no error occurred.
<errorMessage>	Shows an explanative error message.
<warningCode>	Shows an internal warning code, -1 is shown if no warning occurred.
<warningMessage>	Shows an explanative warning message.