vtwsclib – vtiger CRM Web Services

Client Library
version 1.4

http://forge.vtiger.com/projects/vtwsclib
Table of Contents
Version History................................................................................................................... 4
About................................................................................................................................ 5
Installation.........................................................................................................................6
Requirement...................................................................................................................... 6
PHP Client Library Overview................................................................................................. 7
Class overview................................................................................................................7
Vtiger_WSClient(url)................................................................................................... 7
Boolean doLogin(username, accesskey)......................................................................... 7
Object doListTypes()....................................................................................................9
Object doDescribe(module)........................................................................................ 10
Object doCreate(module, valuesmap).......................................................................... 11
Object doRetrieve(record).......................................................................................... 12
Object doQuery(query).............................................................................................. 13
Object doInvoke(method, params, type)...................................................................... 14
Object lastError()...................................................................................................... 15
Object toJSON(inputString)........................................................................................ 16
String toJSONString(input)......................................................................................... 16
Javascript Client Library Overview....................................................................................... 17
Class overview.............................................................................................................. 17
Vtiger_WSClient(url)..................................................................................................17
doLogin(username, accesskey, callback)......................................................................18
Callback Argument.................................................................................................... 18
doListTypes(callback)................................................................................................. 19
doDescribe(module, callback)..................................................................................... 20
doCreate(module, valuesmap, callback)....................................................................... 21
doRetrieve(record, callback)....................................................................................... 22
doQuery(query, callback)........................................................................................... 23
doInvoke(callback, method, params, type)................................................................... 24
lastError()................................................................................................................ 25
Object toJSON(inputString)........................................................................................ 26
String toJSONString(input)......................................................................................... 26
Python Client Library Overview........................................................................................... 27
Class overview.............................................................................................................. 27
Vtiger_WSClient(url)..................................................................................................27
Object doLogin(username, accesskey)......................................................................... 28
Object doListTypes().................................................................................................. 29

http://forge.vtiger.com/projects/vtwsclib
 Object doDescribe(module)........................................................................................ 30
Object doCreate(module, valuesmap).......................................................................... 31
Object doRetrieve(record).......................................................................................... 32
Object doQuery(query).............................................................................................. 33
Object doInvoke(method, params, type)...................................................................... 34
Object lastError()...................................................................................................... 35
Object toJSON(inputString)........................................................................................ 36
String toJSONString(input)......................................................................................... 36
Java Client Library Overview...............................................................................................37
Third-Party Libraries...................................................................................................... 37
Class overview.............................................................................................................. 37
WSClient(url)............................................................................................................37
boolean doLogin(String username, String accesskey).....................................................38
java.util.Map doListTypes()......................................................................................... 39
org.json.simple.JSONObject doDescribe(String module)................................................. 40
org.json.simple.JSONObject doCreate(String module, java.util.Map valuesmap) ................41
org.json.simple.JSONObject doRetrieve(Object record)..................................................42
org.json.simple.JSONArray doQuery(String query)........................................................43
Object doInvoke(String method, Object params) – type defaults to GET.......................... 44
Object doInvoke(String method, Object params, String type).........................................44
Object lastError()...................................................................................................... 45
Object toJSON(String inputString)............................................................................... 46
String toJSONString(Object input)............................................................................... 46
Appendix – I : API Changes................................................................................................ 47
doListTypes.................................................................................................................. 47
Appendix – II: Java library dependency................................................................................47
Appendix III – Examples.................................................................................................... 48
Creating record having reference to other record..............................................................48

http://forge.vtiger.com/projects/vtwsclib
Version History

Version Release Date Highlights

1.4 2009.09.23 * Added Java client library support

1.3 2009.09.22 * Added doInvoke API to invoke custom webservice functions

1.2 2009.03.28 * Added lastError API to get the last operation error information.
* Changed doListTypes API result datastructure to Map instead of List.
1.1 2008.11.06 * Minor bug fix

1.0 2008.10.23 * Provide Basic API wrapper for Webservice support

http://forge.vtiger.com/projects/vtwsclib
About

vtwsclib (vtiger CRM Web Services Client Library) provides wrapper classes to use vtiger CRM web
services. Using this library you can write new application that integrate with vtiger CRM easily.

The current release of vtwsclib library provides web services client wrappers for PHP, JS and
Python, Java languages.

http://forge.vtiger.com/projects/vtwsclib
Installation

Unpack the vtwsclib-x.y.zip into the folder where your web services client application will
reside.

Requirement

You will need to enable the php_curl extension when using PHP Client Library.

http://forge.vtiger.com/projects/vtwsclib
PHP Client Library Overview

PHP Client wrapper (class Vtiger_WSClient) provides the following functions:

➢ doLogin
➢ doListTypes
➢ doDescribe
➢ doCreate
➢ doRetrieve
➢ doQuery
➢ doInvoke
➢ lastError
➢ toJSON
➢ toJSONString

Class overview
class Vtiger_WSClient is defined in the file vtwsclib/Vtiger/WSClient.php. Include this class in your
PHP web services client application code as illustrated below

Vtiger_WSClient(url)
Parameters url – vtiger CRM URL

Return value Instantiates class object

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';

$client = new Vtiger_WSClient($url);

?>

Boolean doLogin(username, accesskey)

Parameters username – vtiger CRM username
accesskey – users unique key (See My Preferences in vtiger CRM as shown here)
Return value True – on success
False – on failure

Details This function initializes Vtiger_WSClient with sessionId on successful login which is
required for performing other operations.

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';

http://forge.vtiger.com/projects/vtwsclib
 else echo 'Login Successful';

?>
vtiger CRM User Preferences

http://forge.vtiger.com/projects/vtwsclib
Object doListTypes()
Parameters
Return value Module information accessible to logged in user.

Details
Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
$modules = $client->doListTypes();
foreach($modules as $modulename => $moduleinfo) {
echo “ModuleName: $modulename\n<BR>”;
}
}
?>

http://forge.vtiger.com/projects/vtwsclib
Object doDescribe(module)
Parameters module – module name
Return value Details of the module as Map

Details Information about fields of the module, permission to create, delete, update records of
the module can be obtained.

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
$modules = $client->doListTypes();
foreach($modules as $modulename => $moduleinfo) {
$describe = $client->doDescribe($module);
$cancreate = $describe[createable];
$canupdate = $describe[updateable];
$candelete = $describe[deleteable];
$canread = $describe[retrieveable];
$fields = $describe[fields];
}

}
?>

http://forge.vtiger.com/projects/vtwsclib
Object doCreate(module, valuesmap)
Parameters module – module name
valuesmap – field name and field value pairs
Return value On successful creation New record information will be returned.
Creation may fail if mandatory field name and value pair is not set.

Details Creating new records in the module can be done using this method.
Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
$module = 'Leads';
$record = $client->doCreate($module,
Array('lastname'=>'CRMLead', 'company'=>'vtiger'));

if($record) {
$recordid = $client->getRecordId($record['id']);
}
}
?>
NOTE: The server returns record['id'] in the format <moduleid>'x'<recordid>.
Use method getRecordId method can be used to retrieve only the record id
part from the returned record id from the server.

http://forge.vtiger.com/projects/vtwsclib
Object doRetrieve(record)
Parameters record – identifier having the format <moduleid>'x'<recordid>
Return value If specified module record is found its information is returned otherwise False.
Creation may fail if mandatory field name and value pair is not set.

Details Retrieve information of existing record of the module.

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
// Retrieve Contacts record with id 110
$record = '4x110';
$recordInfo = $client->doRetrieve($record);
if($recordInfo) {
$lastname = $recordInfo['lastname'];
}
}
?>

http://forge.vtiger.com/projects/vtwsclib
Object doQuery(query)
Parameters query – SELECT query to use for fetching the records.
Return value

Details Webservices provides custom subset of SQL support to work with vtiger CRM.
Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
// Retrieve Accounts matching name 'vtiger'
$query = “SELECT * FROM Accounts WHERE accountname LIKE 'vtiger'”;
$records = $client->doQuery($query);

if($records) {
$columns = $client->getResultColumns($records);
foreach($records as $record) {
// Process record information
}
}
}
?>

NOTE: Use getResultColumns API to retrieve column names available in the result records.

Please refer the webservices documentation to know more about SQL format and
support.

http://forge.vtiger.com/projects/vtwsclib
Object doInvoke(method, params, type)
Parameters method – Name of the webservice method to invoke
params – Parameters to the webservice method
type – POST/GET transport type to use to invoke the method
Return value

Details This method provides the ability to invoke the custom webservice method that is
exposed by REST interface.

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
$response = $client->doInvoke(
'custom_wsmethod',
array( 'firstparam' => 'F', 'secondparam' => 'S',
'POST')
);
$wasError = $client->lastError();
if($wasError) {
var_dump($client->lastError());
} else {
// Take action on $response
}
}
?>

http://forge.vtiger.com/projects/vtwsclib
Object lastError()
Parameters
Return value Map containing (code, message) if the last operation failed or else false

Details
Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$login = $client->doLogin('admin', 'KpS9EjNz16JtPmoe');

if(!$login) echo 'Login Failed';
else {
// Retrieve Accounts matching name 'vtiger'
$query = “SELECT * FROM Accounts WHERE WRONGQUERY”;
$records = $client->doQuery($query);
$wasError= $client->lastError();
if($wasError) {
echo $wasError['code'] . ':' . $wasError['message'];
}
}
?>

NOTE The lastError information is reset after every operation is executed.

http://forge.vtiger.com/projects/vtwsclib
Object toJSON(inputString)
Parameters inputString – json format input string
Return value PHP Array or Map or String
Details Converts the given input JSON format string to PHP Object
Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$phpmap = $client->toJSON( '{ “A” : “B” }' );

?>

String toJSONString(input)
Parameters input – PHP Array or Map or String

Return value JSON string

Details Converts the given input to JSON format string

Example <?php
include_once('vtwsclib/Vtiger/WSClient.php');

$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);

$jsonstring = $client->toJSONString( { 'a'=>'ValueA'} );

?>

http://forge.vtiger.com/projects/vtwsclib
Javascript Client Library Overview

The following script includes are required on your page to use web services through Javascript
client:

<script type='text/javascript' src='vtwsclib/third-party/js/jquery.js'></script>

<script type='text/javascript' src='vtwsclib/third-party/js/md5.js'></script>
<script type='text/javascript' src='vtwsclib/Vtiger/WSClient.js'></script>

Javascript Client wrapper (Vtiger_WSClient) provides the following functions:

➢ doLogin
➢ doListTypes
➢ doDescribe
➢ doCreate
➢ doRetrieve
➢ doQuery
➢ doInvoke
➢ lastError
➢ toJSON
➢ toJSONString

Class overview

class Vtiger_WSClient is defined in the file vtwsclib/Vtiger/WSClient.js

Vtiger_WSClient(url)
Parameters url – vtiger CRM URL

Return value Instantiates class object

Example <script type='text/javascript'>

var url = 'http://en.vtiger.com/wip';

var client = new Vtiger_WSClient(url);

</script>

http://forge.vtiger.com/projects/vtwsclib
doLogin(username, accesskey, callback)
Parameters username – vtiger CRM username
accesskey – users unique key (See My Preferences in vtiger CRM as shown here)
callback – callback argument (See details explained here)

Callback True – on success

First parameter False – on failure
Details Initializes Vtiger_WSClient with sessionId on successful login which is required for
performing other operations. Function referenced via callback will be invoked.
Example <script type='text/javascript'>

var url = 'http://en.vtiger.com/wip';

var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', callback);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(result) alert('Login was successful');
else alert('Login failed');
}

</script>

Callback Argument

Asynchronous calls are made to service using AJAX request by webservice client functions.

Hence callback function should be sent, which will be invoked after the response is obtained from
the server.

The callback argument can be any of the following:

➢ Function Reference
➢ Callback map having the following format:
{
'function' : <Function Reference>,
'arguments' : {'arg1' : 'value1', 'arg2' : ['value2']}
}

Webservice function will invoke the callback function passing the result as the first parameter. If
callback map was sent then the reference sent via 'function' key will be invoked with result as the
first parameter and second parameter will be values referenced by 'arguments' key of the callback
map.

http://forge.vtiger.com/projects/vtwsclib
doListTypes(callback)
Parameters callback – callback argument (See details explained here)
Callback Module information accessible to logged in user.
First parameter

Details
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else getModules();
}
function getModules() {
client.doListTypes(postGetModules);
// postGetModules gets a call once request is completed
}
function postGetModules(modules, args) {
if(modules) alert(client.toJSONString(modules));
}

</script>

http://forge.vtiger.com/projects/vtwsclib
doDescribe(module, callback)
Parameters module – module name
callback – callback argument (See details explained here)
Callback Details of the module as Map
First Parameter
Details Information about fields of the module, permission to create, delete, update records of
the module can be obtained.
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else getModuleDetails();
}
function getModuleDetails() {
var module = 'Leads';
var callback = {
'function' : processModuleDetails,
'arguments': { 'moduleName' : module }
};
client.doDescribe(callback);
// processModuleDetails gets a call once request is completed
}
function processModuleDetails(result, args) {
var module = args.moduleName;
if(result)
alert('Module = ' + module + ', Details = ' +
client.toJSONString(result));
}
</script>

http://forge.vtiger.com/projects/vtwsclib
doCreate(module, valuesmap, callback)
Parameters module – module name
valuesmap – field name and field value pairs
callback – callback argument (See details explained here)
Callback On successful creation New record information will be sent.
First Parameter Creation may fail if mandatory field name and value pair is not set.

Details Creating new records in the module can be done using this method.
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else createModuleRecord();
}
function createModuleRecord() {
var module = 'Leads';
var valuesmap = {
'lastname' : 'CRMLead', 'company':'vtiger'
} ;
client.doCreate(module, valuesmap, afterCreateRecord);

// afterCreateRecord gets a call once request is completed

}
function afterCreateRecord(result, args) {
if(result)
alert('Record Id = ' + client.getRecordId(result.id));
}
</script>
NOTE: The server returns record['id'] in the format <moduleid>'x'<recordid>.
Use method getRecordId method can be used to retrieve only the record id
part from the returned record id from the server.

http://forge.vtiger.com/projects/vtwsclib
doRetrieve(record, callback)
Parameters record – identifier having the format <moduleid>'x'<recordid>
callback – callback argument (See details explained here)
Callback If specified module record is found its information is sent, otherwise False
First Parameter Creation may fail if mandatory field name and value pair is not set.

Details Retrieve information of existing record of the module.

Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else getModuleRecord();
}
function getModuleRecord() {
var record = '4x110';
client.doRetrieve(record, processModuleRecord);

// processModuleRecord gets a call once request is completed

}
function processModuleRecord(result, args) {
if(result)
alert('Record Id = ' + client.getRecordId(result.id));
}
</script>

http://forge.vtiger.com/projects/vtwsclib
doQuery(query, callback)
Parameters query – SELECT query to use for fetching the records.
callback – callback argument (See details explained here)
Callback Result sent from the server.
First Parameter
Details Webservices provides custom subset of SQL support to work with vtiger CRM.

Example <script type='text/javascript'>

var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else execQuery();
}
function execQuery() {
var query = “SELECT * FROM Accounts “ +
“WHERE accountname LIKE '%vtiger%' ”;

client.doQuery(query, postExecQuery);

// postExecQuery gets a call once request is completed

}
function postExecQuery(result, args) {
if(result) {
var columns = client.getResultColumns(result);
alert('COLUMNS: ' + client.toJSONString(columns));
alert(client.toJSONString(result));
}
}
</script>

NOTE: Use getResultColumns API to retrieve column names available in the result records.

Please refer the webservices documentation to know more about SQL format and
support.

http://forge.vtiger.com/projects/vtwsclib
doInvoke(callback, method, params, type)
Parameters callback – callback argument (See details explained here)
method – Name of the webservice method to invoke
params – Parameters to the webservice method
type – POST/GET transport type to use to invoke the method
Callback Result sent from the server.
First Parameter
Details This method provides the ability to invoke the custom webservice method that is
exposed by REST interface.
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else invokeMethod();
}
function invokeMethod() {
client.doInvoke(postInvoke, 'custom_wsmethod, { 'firstparam' :
'F', 'secondparam' : 'S'} );

// postInvoke gets a call once request is completed

}
function postInvoke(result, args) {
if(result == false) {
alert(client.lastError()['message']);
} else {
// Process result
}
}
</script>

http://forge.vtiger.com/projects/vtwsclib
lastError()
Parameters
Callback Map containing (code, message) if the last operation failed or else false
First parameter

Details
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

client.doLogin('admin', 'KpS9EjNz16JtPmoe', postLogin);

// postLogin function gets a call once request is completed

function postLogin(result, args) {

if(!result) alert('Login failed');
else execQuery();
}
function execQuery() {
var query = “SELECT * FROM Accounts WRONGQUERY“;

client.doQuery(query, postExecQuery);

// postExecQuery gets a call once request is completed

}
function postExecQuery(result, args) {
if(!result) {
var wasError = client.lastError();
alert('ERROR CODE: ' + wasError['code'] + ', MESSAGE: ' +
wasError['message']);
}
}
</script>

NOTE The lastError information is reset after every operation is executed.

http://forge.vtiger.com/projects/vtwsclib
Object toJSON(inputString)
Parameters inputString – json format input string
Return value Javascript Array or Map or String
Details Converts the given input JSON format string to Javascript Object
Example <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

var jsobj = client.toJSON( '{ “A” : “B” }' );

</script>

String toJSONString(input)
Parameters input – Javascript Array or Map or String

Return value JSON string

Details Converts the given input to JSON format string

Example <script type='text/javascript'>

var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);

var jsonstring = client.toJSONString( { 'a'=>'ValueA'} );

</script>

http://forge.vtiger.com/projects/vtwsclib
Python Client Library Overview

Python Client wrapper (Vtiger_WSClient) provides the following functions:

➢ doLogin
➢ doListTypes
➢ doDescribe
➢ doCreate
➢ doRetrieve
➢ doQuery
➢ doInvoke
➢ lastError
➢ toJSON
➢ toJSONString

Class overview

class Vtiger_WSClient is defined in the file vtwsclib/Vtiger/WSClient.py

Vtiger_WSClient(url)
Parameters url – vtiger CRM URL

Return value Instantiates class object

Example import sys

# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

http://forge.vtiger.com/projects/vtwsclib
Object doLogin(username, accesskey)
Parameters username – vtiger CRM username
accesskey – users unique key (See My Preferences in vtiger CRM as shown here)
Return value True – on success
False – on failure

Details Initializes Vtiger_WSClient with sessionId on successful login which is required for
performing other operations. Function referenced via callback will be invoked.

Example import sys

# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if login:
print 'Login Successful'
else:
print 'Login Failed!'

http://forge.vtiger.com/projects/vtwsclib
Object doListTypes()
Parameters
Return value Module information accessible to logged in user.

Details
Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
result = client.doListTypes()
for modulekey in result:
print 'Module Name: ', result[modulekey]['name']

http://forge.vtiger.com/projects/vtwsclib
Object doDescribe(module)
Parameters module – module name
Return value Details of the module as Map

Details Information about fields of the module, permission to create, delete, update records of
the module can be obtained.

Example import sys

# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
moduleInfo = client.doDescribe('Leads')
print 'ModuleInfo: ', moduleInfo

http://forge.vtiger.com/projects/vtwsclib
Object doCreate(module, valuesmap)
Parameters module – module name
valuesmap – field name and field value pairs
Return value On successful creation New record information will be returned back.
Creation may fail if mandatory field name and value pair is not set.

Details Creating new records in the module can be done using this method.
Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
recordInfo = client.doCreate('Leads',
{ 'lastname' : 'CRMLead', 'company' : 'vtiger' })
print 'RecordId: ', client.getRecordId(recordInfo['id'])

NOTE: The server returns record['id'] in the format <moduleid>'x'<recordid>.

Use method getRecordId method can be used to retrieve only the record id
part from the returned record id from the server.

http://forge.vtiger.com/projects/vtwsclib
Object doRetrieve(record)
Parameters record – identifier having the format <moduleid>'x'<recordid>
Return value If specified module record is found its information is sent, otherwise False
Creation may fail if mandatory field name and value pair is not set.

Details Retrieve information of existing record of the module.

Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
# Fetch contact record with id 110
record = '4x110'
recordInfo = client.doRetrieve(record)
print 'RecordId: ', client.getRecordId(recordInfo['id'])

http://forge.vtiger.com/projects/vtwsclib
Object doQuery(query)
Parameters query – SELECT query to use for fetching the records.
Return value Result sent from the server.

Details Webservices provides custom subset of SQL support to work with vtiger CRM.
Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
# Search for Accounts with name like 'vtiger'
query = “SELECT * FROM Accounts WHERE accountname LIKE
'%vtiger%'”
result = client.doQuery(query)
if(result):
columns = client.getResultColumns(result)
print 'Columns: ', columns
print 'Result : ', result

NOTE: Use getResultColumns API to retrieve column names available in the result records.

Please refer the webservices documentation to know more about SQL format and
support.

http://forge.vtiger.com/projects/vtwsclib
Object doInvoke(method, params, type)
Parameters method – Name of the webservice method to invoke
params – Parameters to the webservice method
type – POST/GET transport type to use to invoke the method
Return value Result sent from the server.

Details This method provides the ability to invoke the custom webservice method that is
exposed by REST interface.

Example import sys

# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
# Invoke custom method with parameters
result = client.doInvoke('custom_wsmethod', {'firstparam':'f',
'secondparam' : 's'} )
if(result):
# Process the result
else:
print 'ERROR: ', client.lastError();

http://forge.vtiger.com/projects/vtwsclib
Object lastError()
Parameters
Return value Map containing (code, message) if the last operation failed or else false

Details
Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

login = client.doLogin('admin', 'KpS9EjNz16JtPmoe')

if not login:
print 'Login Failed!'
else:
# Search for Accounts with name like 'vtiger'
query = “SELECT * FROM Accounts WHERE WRONGQUERY”
result = client.doQuery(query)
if(result):
columns = client.getResultColumns(result)
print 'Columns: ', columns
print 'Result : ', result
else:
errorInfo = client.lastError()
print 'Error Code: ', errorInfo['code']
print 'Message : ', errorInfo['message']

NOTE: The lastError information is reset after every operation is executed.

http://forge.vtiger.com/projects/vtwsclib
Object toJSON(inputString)
Parameters inputString – json format input string
Return value Python Array or Map or String
Details Converts the given input JSON format string to Python Object
Example import sys
# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

pyobj = client.toJSON( '{ “A” : “B” }' );

String toJSONString(input)
Parameters input – Python Array or Map or String

Return value JSON string

Details Converts the given input to JSON format string

Example import sys

# Absolute/Relative path of vtwsclib/Vtiger folder
sys.path.append('vtwsclib/Vtiger')

from WSClient import *

# Create Vtiger Webservice client

client = Vtiger_WSClient('http://en.vtiger.com/wip')

jsonstring = client.toJSONString( { 'a'=>'ValueA'} );

http://forge.vtiger.com/projects/vtwsclib
Java Client Library Overview

Java Client wrapper (com.vtiger.vtwsclib.WSClient) provides the following functions:

➢ doLogin
➢ doListTypes
➢ doDescribe
➢ doCreate
➢ doRetrieve
➢ doQuery
➢ doInvoke
➢ lastError
➢ toJSON
➢ toJSONString

Third-Party Libraries

● Make sure to have vtwsclib/java and vtwsclib/java/deps on the CLASSPATH when invoking
through java command line.

● vtwsclib.jar depends on HTTP Components library which are bundled under

vtwsclib/java/deps (Apache License 2.0)

● vtwsclib.jar is bundled with json-simple library which can be re-used for JSON manipulation
in your application. (Apache License 2.0)

Class overview

Class com.vtiger.vtwsclib.WSClient is defined in the core library class which is packaged in the
java/vtwsclib.jar

WSClient(url)
Parameters url – vtiger CRM URL

Return value Instantiates class object

Example import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

http://forge.vtiger.com/projects/vtwsclib
boolean doLogin(String username, String accesskey)
Parameters username – vtiger CRM username
accesskey – users unique key (See My Preferences in vtiger CRM as shown here)
Return value True – on success
False – on failure

Details Initializes Vtiger_WSClient with sessionId on successful login which is required for
performing other operations. Function referenced via callback will be invoked.

Example import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
System.out.println("Logged in");
}

http://forge.vtiger.com/projects/vtwsclib
java.util.Map doListTypes()
Parameters
Return value Module information accessible to logged in user.

Details
Example import java.util.Iterator;
import java.util.Map;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
Map types = client.doListTypes();
Iterator iterator = types.keySet().iterator();
while(iterator.hasNext()) {
Object key = iterator.next();
Map moduleInfo = (Map) types.get(key);
System.out.println("Module name: " +
moduleInfo.get("name"));
}
}

http://forge.vtiger.com/projects/vtwsclib
org.json.simple.JSONObject doDescribe(String module)
Parameters module – module name
Return value Details of the module as Map

Details Information about fields of the module, permission to create, delete, update records of
the module can be obtained.

Example import org.json.simple.JSONObject;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
JSONObject describeResult = client.doDescribe("Leads");

if(client.hasError(describeResult)) {
System.out.println("Describe failed!" +
client.lastError());
} else {
System.out.println(describeResult);
}
}

http://forge.vtiger.com/projects/vtwsclib
org.json.simple.JSONObject doCreate(String module, java.util.Map valuesmap)
Parameters module – module name
valuesmap – field name and field value pairs
Return value On successful creation New record information will be returned back.
Creation may fail if mandatory field name and value pair is not set.

Details Creating new records in the module can be done using this method.
Example import java.util.HashMap;
import java.util.Map;
import org.json.simple.JSONObject;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
Map valuesmap = new HashMap();
valuesmap.put("lastname", "Test Lastname");
valuesmap.put("company", "Test Company");

JSONObject createResult = client.doCreate(

"Leads", valuesmap);
if(client.hasError(createResult)) {
System.out.println("Create failed!" +
client.lastError());
} else {
System.out.println(createResult);
}
}
NOTE: The server returns record['id'] in the format <moduleid>'x'<recordid>.
Use method WSClient.getRecordId method can be used to retrieve only the
record id part from the returned record id from the server.

http://forge.vtiger.com/projects/vtwsclib
org.json.simple.JSONObject doRetrieve(Object record)
Parameters record – identifier having the format <moduleid>'x'<recordid>
Return value If specified module record is found its information is sent, otherwise False
Creation may fail if mandatory field name and value pair is not set.

Details Retrieve information of existing record of the module.

Example import org.json.simple.JSONObject;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
/* Fetch contact record with id 110 */
JSONObject retrieveInfo = client.doRetrieve("4x110");

if(client.hasError(retrieveInfo)) {
System.out.println("Retrieve failed!" +
client.lastError());
} else {
System.out.println(retrieveInfo);
}
}

http://forge.vtiger.com/projects/vtwsclib
org.json.simple.JSONArray doQuery(String query)
Parameters query – SELECT query to use for fetching the records.
Return value Result sent from the server.

Details Webservices provides custom subset of SQL support to work with vtiger CRM.
Example import java.util.Iterator;

import org.json.simple.JSONArray;
import org.json.simple.JSONObject;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {

JSONArray queryResult = client.doQuery("SELECT * FROM Leads");

if(client.hasError(queryResult)) {
System.out.println("Query failed!" + client.lastError());
} else {
System.out.println("# Result Rows " + queryResult.size());

System.out.println("# " + client.getResultColumns(queryResult));

Iterator resultIterator = queryResult.iterator();

while (resultIterator.hasNext()) {
JSONObject row = (JSONObject) resultIterator.next();
Iterator rowIterator = row.keySet().iterator();

System.out.println("---");
while (rowIterator.hasNext()) {
Object key = rowIterator.next();
Object val = row.get(key);
System.out.println(" " + key + " : " + val);
}
}
}
}

NOTE: Use getResultColumns API to retrieve column names available in the result records.

Please refer the webservices documentation to know more about SQL format and
support.

http://forge.vtiger.com/projects/vtwsclib
Object doInvoke(String method, Object params) – type defaults to GET
Object doInvoke(String method, Object params, String type)
Parameters method – Name of the webservice method to invoke
params – Parameters to the webservice method
type – POST/GET transport type to use to invoke the method

Return value Result sent from the server.

Details This method provides the ability to invoke the custom webservice method that is
exposed by REST interface.
Example import java.util.HashMap;
import java.util.Map;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {

// Delete Leads module record with id = 179

Map params = new HashMap();
params.put("id", "2x179");

Object deleteResult = client.doInvoke("delete", params,

"POST");

if (client.hasError(deleteResult)) {
System.out.println("Deletion failed!" +
client.lastError());
} else {
System.out.println("Result " + deleteResult);
}
}

http://forge.vtiger.com/projects/vtwsclib
Object lastError()
Parameters
Return value JSON Map containing (code, message) if the last operation failed or Exception that
happened while executing the operation.
Details

Example import org.json.simple.JSONArray;

import org.json.simple.JSONObject;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

boolean result = client.doLogin(“admin”, “KpS9EjNz16JtPmoe”);

if(result == false) {
System.out.println("Login failed!");
System.out.println(client.lastError());
} else {
JSONArray queryResult = client.doQuery("Wrong Query");
if(client.hasError(queryResult)) {
Object errorInstance = client.lastError();

if(errorInstance instanceof JSONObject) {

String code =
((JSONObject)errorInstance).get("code").toString();
String message =
((JSONObject)errorInstance).get("message").toString();

System.out.println("CODE: " + code + ", MESSAGE: " +

message);
}
}
}

http://forge.vtiger.com/projects/vtwsclib
Object toJSON(String inputString)
Parameters inputString – json format input string
Return value org.json.simple.JSONArray or org.json.simple.JSONObject
Details Converts the given input JSON format string to JSON Java Object
Example import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

Object jsonObj = client.toJSON( “{ \“A\” : \“B\” }”);

String toJSONString(Object input)

Parameters input – Java JSON Array or Map or String

Return value JSON string

Details Converts the given input to JSON format string

Example import java.util.HashMap;

import java.util.Map;

import com.vtiger.vtwsclib.WSClient;

/* Create Vtiger Webservice client */

WSClient client = new WSClient(“http://en.vtiger.com/wip”);

Map map = new HashMap();

map.put("A", "b");

String jsonString = client.toJSONString(map);

http://forge.vtiger.com/projects/vtwsclib
Appendix – I : API Changes

doListTypes

version 1.1: List of module names was returned

[ 'Module1', 'Module2', ...]

version 1.2: Module information is returned as Map

{
'Module1' : { 'name' : MODULENAME },
'Module2' : { 'name' : MODULENAME }
}

Appendix – II: Java library dependency

vtwsclib java library is packaged in vtwsclib.jar and depends on HTTP Components Client library.

The Class-Path in the MANIFEST file is configured to lookup the deps directory in the same folder
where vtwsclib.jar resides.

java -cp your_class_path;../wip/vtwsclib/dist/vtwsclib.jar your.package.className

If you experience the run-time exception like:

Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/http/impl/

client/DefaultHttpClient
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(Unknown Source)
at java.security.SecureClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.defineClass(Unknown Source)
at java.net.URLClassLoader.access$100(Unknown Source)
at java.net.URLClassLoader$1.run(Unknown Source)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
at java.lang.ClassLoader.loadClass(Unknown Source)
at java.lang.ClassLoader.loadClassInternal(Unknown Source)
at com.vtiger.vtwsclib.WSClient.<init>(WSClient.java:53)
at com.vtiger.tests.vtwsclib.TestWSClient.main(TestWSClient.java:20)

Please make review your CLASSPATH settings.

http://forge.vtiger.com/projects/vtwsclib
Appendix III – Examples

Creating record having reference to other record.

This example demonstrates creating Potentials (Opportunities) record and link it to existing
Accounts (Organizations) record.

include_once 'vtwsclib/Vtiger/WSClient.php';

$client = new Vtiger_WSClient('http://en.vtiger.com/wip');

$client->doLogin('admin', 'ACCESSKEY');

$organizations = $client->doQuery(
"SELECT id FROM Accounts WHERE accountname='vtiger'");

if ($organizations) {
$parentRecord = $organizations[0];

$data = array(
'potentialname' => 'Test Opportunity Name',
'related_to' => $parentRecord['id'], // (moduleId x recordId)
'closingdate' => date('Y-m-d'),
'sales_stage' => 'Prospecting',
'amount' => '2000'
);
$opportunity = $client->doCreate('Potentials', $data);
if ($opportunity) {
print_r($opportunity);
} else {
echo $client->getLastError();
}
}

http://forge.vtiger.com/projects/vtwsclib