0

VSXi SOAP / Web Services API Guide

This document describes the use of Sansay Web Services (WS hereafter) Client version 1.3.1.15. It uses VSXi Web Services to upload and download configuration files and retrieve some of the system's statistics data. Request and response messages are encoded/decoded using XML and exchanged using SOAP protocol.

Sansay WS Client is a command line utility. This document lists all available commands and their options and examples of use.

Sample XML data files can be obtained by downloading data from the VSXi server.

Command Descriptions

Upload and Download Data Formats

Data can be uploaded or downloaded to/from VSXi server in two formats:

  • XML data in plain text files
  • XML data in zipped text files

Plain text format is just part of SOAP message and there is a size limitation, see below. Zipped XML text format is currently used for some DB tables that can be large. In this case there is no size limitation; however XML file has to be zipped before upload. Also, downloaded data is in zipped XML files. 

WS client commands that have “Large” as part of operation name are used to upload or download data in zipped XML (binary) format. 

Maximum size of uploaded files in text format

Some tables in DB, like table route are too big to be downloaded or uploaded in one try. During download process Sansay server will export 5000 routes in one XML file. During upload the server can't control the number of elements in XML file. If there is too much data it causes the exception due to the limitations of stack used to implement WS. It is strongly recommended that XML files uploaded to Sansay server don't have more than 5000 elements. Currently only code used to download routes, digit mappings and subscriber tables uses this logic. It splits route and digit mapping table to chunks of 5000 elements, and subscriber table is split to chunks of 10000 entries.

Download of tables with more than 5000 entries in text format

If the data is split to multiple files during download process data is stored in files that have index appended to file name. For example, route_0.xml, route_1.xml...

Usage, options and commands list

Sansay VSXi WS client commands are invoked by:

java –jar VSXi_WS_Client.jar [-options] <command> [args...]

Available options are:

Option Description
-a<ipaddr> IP address of the VSXi server
-u<username> User Name
-p<password> User's Password
-version Print product version and exit
-? or –-help Print help message and exit

Note: Options –version, -? and --help don’t require user to specify other options (IP address...). To invoke a command that actually connects to a server, IP address, UserName and Password are required.

 

Available commands are:

Command Description
upload Uploads data in a XML file to the server and replaces the data in a specified table. 
replaceLarge Replaces data in specified table with data supplied in zipped XML file. 
download Downloads data from the specified table to the XML file. 
downloadLarge Downloads data from specified table to zipped XML file. 
delete Deletes entries in the XML file from the specified table. 
deleteLarge Deletes entries in the zipped XML file from the specified table. 
update Updates entries from the XML file in the specified table. If the entry is not currently in DB it’s inserted. 
updateLarge Updates entries from the zipped XML file in the specified table. If the entry is not currently in DB it’s inserted. 
query Query specified table using the specified query string and dowloads data to the XML file. 
stats Downloads real-time stats in XML format.
system Downloads real time system status. 

Certain commands may require more time to complete (several minutes) if the table that the command is operating on is big. This applies mostly to the route and digit mapping tables that in some systems may have hundreds of thousands of rows.

 

Downloading configuration data from the database

The syntax of command used to download data from the specified table in the database to the XML file is:

download <xml_file_name> <table>

Argument Description
xml_file_name The name of XML file with the downloaded data from VSXi 
Table Can be one of the following:
  • route
  • routegroup
  • routetable
  • resource
  • resourceblock
  • digit_mapping_index
  • digit_mapping
  • subscriber
  • serviceport
  • virtualip

The example of downloading the data:

java –jar VSXi_WS_Client.jar -a192.168.1.2  -usuperuser -psansay1234 download routegroup.xml routegroup

When downloading data and table parameter is route, digit_mapping or subscriber, Sansay WS client can create multiple files in case that the corresponding DB tables have more than 5000 entries in case of route and digit_mapping and 10000 entries in case of subscriber table. Each file will have 5000 entries (10000 in case of subscriber), and the last file can have less than that, remaining number of N * 5000 to the total number of entries in DB table. Files will be named xml_file_name_N.xml. N is 0, 1, 2... In this case WS client requests next file from the server until all data from the requested table is downloaded.

Downloading large amount of configuration data from the database

The syntax of command used to download large amount of data from the specified table in the database is:

downloadLarge <xml_zip_file_name> <table>

Argument Description
xml_zip_file_name  The name of XML file with the data to be added to the table VSXi's database 
Table Can be one of the following:
  • route
  • subscriber
  • digit_mapping
  • systemConfiguration
  • hardwareConfiguration

The example of downloading data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser -psansay1234 downloadLarge route.zip route

Downloading real-time statistics data

The syntax of command used to download real-time statistics to the XML file is:

stats <xml_file_name> <stat_type>

Argument Description
xml_file_name The name of XML file with the downloaded real-time statistics data from VSXi.
stat_type Can be one of the following:
  • resource
  • realtime
  • media_server
  • resource_detail
  • sub_stat

The example of querying the real-time statistics data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser   -psansay1234 stats realtime.xml realtime 

Downloading real-time system status

The syntax of command used to download real-time system status to the XML file is:system <txt_file_name>

Argument Description
txt_file_name The name of text file with the downloaded real-time system data from VSXi.
   

The example of querying the real-time system data:


java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser   -psansay1234 system system.xml

 

Deleting configuration data from database

The syntax of command used to delete data in the XML file from the specified table in  the database is:

delete <xml_file_name> <table>

Argument Description
xml_file_name The name of XML file with the data to be deleted from the table in VSXi database. 
Table Can be one of the following:
  • route
  • routegroup
  • routetable
  • resource
  • resourceblock
  • digit_mapping_index
  • digit_mapping
  • subscriber
  • serviceport
  • virtualip

Example of deleting the data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser -psansay1234 delete resource.xml resource

 

Deleting large amount of configuration data from the database

The syntax of command used to delete large amount of data in the XML file from the specified table in the database is:

deleteLarge <xml_zip_file_name> <table>

Argument Description
xml_zip_file_nam  The name of XML file with the data to be added to the table VSXi database. 
Table One of the following:
  • route
  • subscriber
  • digit_mapping

The example of deleting data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser  -psansay1234 deleteLarge routetable.zip routetable

 

Updating configuration data in the database

The syntax of command used to update data in the specified table in the database with the data from the XML file is:

update <xml_file_name> <table>

Argument Description
xml_file_name The name of XML file with the data to be updated in the table in VSXi database. 
Table One of the following:
  • route
  • routegroup
  • routetable
  • resource
  • resourceblock
  • digit_mapping_index
  • digit_mapping
  • subscriber
  • serviceport
  • virtualip

The example of updating the data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser  -psansay1234 update resource.xml resource

 

Updating large amount of configuration data in the database

The syntax of command used to add data in the XML file to the specified table in the database is:

updateLarge <xml_zip_file_name> <table>

Argument Description
xml_zip_file_name  The name of XML file with the data to be added to the table VSXi database. 

Table

One of the following:

  • route
  • subscriber
  • digit_mapping

The example of updating data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser  -psansay1234 updateLarge route.zip route

Data in zip archive that is uploaded to the server can be in one or multiple XML files that are zipped together. The archive cannot contain other zip files.

Replacing configuration data in the database

The syntax of command used to replace data in the specified table in database with data in the XML file is:

upload <xml_file_name> <table>

Argument Description
xml_file_name The name of XML file with data to be uploaded to VSXi. 
Table Can be one of the following:
  • route
  • routegroup
  • routetable
  • resource
  • resourceblock

The example of uploading the data:

java –jar VSXi_WS_Client.jar -a192.168.1.2   -psansay1234 upload routelist.xml route

Replacing large amount of configuration data in the database

The syntax of command used to replace large amount of data in the specified table in database with data in the XML/ZIP file is:

replaceLarge <xml_zip_file_name> <table>

Argument Description
xml_zip_file_name  The name of XML file with data to be uploaded to VSXi. 
Table Can be one of the following:
  • route
  • routesInRouteTable
  • subscriber
  • digit_mapping
  • digitMappingsInDigMapTable
tableID Route Table ID or Digit Mapping Table ID
   

NOTE: Parameter tableID is used only when parameter table has value routesInRouteTable or digitMappingsInDigMapTable. For other values this parameter is ignored, but some value has to be specified in the command line, for example -1.

The example of uploading the data:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -psansay1234 replaceLarge routelist.zip route -usuperuser

Querying specified table in the database

The syntax of command used to query the specified table in the database and download the query result to the specified XML file is

query <xml_file_name> <table> <query_string>

Argument Description
xml_file_name The name of XML file with the downloaded result query from VSXi. 
table Can be one of the following:
  • route
  • digit_mapping
  • resource
query_string “trunk_id='55432'” 
“digit_match='1234'” 

Note: the query string must be surrounded by double quotes! 

The example of querying the table:

java –jar VSXi_WS_Client.jar -a192.168.1.2 -usuperuser  -psansay1234 query route.xml route “trunk_id='500'”

Sansay WS return codes

This paragraph lists codes returned by VSXi server in response to various requests. Each return message has the return code and text message that describes the code.

Code Associated Message Description
200 200 OK General OK response.
  200 OK - uploadXmlFile success. File upload was OK.
300 Finished With Errors File was uploaded but some items failed validation and were discarded. Valid items were processed successfully.
400 400 fail - invalid table specified: + requested table name. Invalid table name.
    Invalid table name.
  400 fail - validation exception XML validation error.
  400 fail - digit match can not be empty Digit match has to be specified for RouteLookUp
  400 – failed Other types of errors (exception)
401 401 Fail - User Not Authorized: Invalid username or no read/write permissions. User is not authorized or doesn't have permissions
  401 Fail - User Not Authorized: invalid user password User password is invalid.
402 402 Fail - This action is not allowed while system is in Load-Balance Slave mode No configuration changes are allowed on slave servers data can only be dowloaded

Error handling when using different data formats upload

When data is uploaded to the VSXi server in plain-text the whole file is validated and if any error is found, the process is aborted and no changes are done to DB. 

In case when “Large” commands are used with compressed (zipped) data, if an error is found in one entry (XML element), that entry is thrown away and error is logged to the user log file. However, the process continues. For example, if one route is found to be invalid, it’s thrown away, but the other routes are processed and stored in DB (updated, replaced, deleted...). In that case the return code is 300, and the message describing the error is “300 Finished With Errors - Validation Errors were detected. Please see User Access Log file for details.”

In both cases errors are logged to User Access Log File that can be found and downloaded in GUI, Trace>User Log tab. Upper box on this page lists all User Log files available for download, and the lower box shows the latest entries in the latest file – user_access.log.

Operational Environment

Java Run-time Environment

Sansay VSXi SOAP Client requires JRE version 1.6 or higher. It is designed to run and tested on Oracle/SUN’s implementation of JRE. It’s also called JVM, and SUN’s implementation’s name is HotSpot.

Operating System Support

Sansay VSXi SOAP Client is written in Java language and it should work under Operating Systems that support Java 1.6 or higher.

Embedding Sansay VSXi SOAP Client in third party applications

Sansay VSXi SOAP Client is intended to be used as a command-line utility. It is possible to use the client in third party application, however, the code is not thread safe. That means that if the application tries to poll more than one VSXi server at the time results will most likely be invalid.

It is possible to use the client from the third party application by executing the Operating System call and calling the Sansay VSXi SOAP Client the same way it is called from the command line.

Reply

null