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:

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:

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>

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>

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>

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>

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>

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>

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>

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>

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>

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>

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>

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.

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.