Está en la página 1de 63

vtiger CRM

MANUAL DE DESARROLLO WEBSERVICES (REST)


versión para vtiger CRM 5.2.x
Primera Edición

vtigerCRM-Spain
JPL TSolucio, S.L.
vtiger CRM v5.2.x:
Manual de Desarrollo Webservices (REST)
Copyright © 2011 JPL TSolucio, S.L. España
Autor: Joe Bordes

Historial de Revisiones
Revisión 01 2011-04-10
Revisión 02 2011-06-01 (acceso svn)

jpl tsolucio c/ joan fuster, 12 Els Poblets, Spain. www.vtiger-spain.com

Aunque se ha adoptado la mayor precaución en la preparación de este libro, el editor no asume ninguna
responsabilidad por errores u omisiones o por daños y perjuicios derivados de la utilización de la información contenida
en este documento.

Jpl tsolucio, s.l. no ofrece ninguna garantía en el uso de vtiger CRM y no asume ninguna responsabilidad por cualquier
error que pueda aparecer en este documento. Tampoco adquiere el compromiso de actualizar la información aquí
contenida.
Índice de contenido
Prólogo................................................................................................................1
Introducción.........................................................................................................2
Formato de Llamada....................................................................................2
Formato de Respuesta.................................................................................2
Operaciones.................................................................................................3
Nombre de Sesión........................................................................................4
Seguridad.....................................................................................................4
Tipos de Datos utilizados.............................................................................4
VtigerObject.............................................................................................4
Id Format..................................................................................................4
Map..........................................................................................................4
TimeStamp...............................................................................................4
GetChallengeResult..................................................................................5
LoginResult...............................................................................................5
SyncResult................................................................................................5
Operaciones.....................................................................................................6
Get Challenge..............................................................................................6
Login............................................................................................................6
Create..........................................................................................................6
Retrieve........................................................................................................7
Update.........................................................................................................7
Delete..........................................................................................................7
Query...........................................................................................................7
Sync.............................................................................................................8
Logout..........................................................................................................9
List Types.....................................................................................................9
Describe.......................................................................................................9
Extend Session...........................................................................................11
Entidades CRM...............................................................................................11
Tipos de campos............................................................................................12
picklist........................................................................................................12
multipicklist................................................................................................12
reference....................................................................................................12
datetime.....................................................................................................12
date............................................................................................................12
time............................................................................................................13
string..........................................................................................................13
text.............................................................................................................13
password....................................................................................................13
boolean......................................................................................................13
integer........................................................................................................13
double........................................................................................................13
decimal......................................................................................................13
owner.........................................................................................................13
autogenerated...........................................................................................13
email..........................................................................................................13
phone.........................................................................................................14
skype..........................................................................................................14
url...............................................................................................................14
file..............................................................................................................14
Problemas conocidos.....................................................................................14
Tutorial vtiger CRM Webservices.......................................................................16
Requerimientos..............................................................................................16
Accediendo al Sistema...................................................................................16
Get Challenge............................................................................................17
Login..........................................................................................................18
Obteniendo Información de los Objetos.........................................................19
List Types...................................................................................................19
Describe.....................................................................................................19
Operaciones de cambio en la aplicación (CRUD)...........................................20
Crear..........................................................................................................20
Ejemplo 1...............................................................................................20
Ejemplo 2...............................................................................................21
Obtener......................................................................................................21
Actualizar...................................................................................................22
Eliminar......................................................................................................23
Operaciones de Consulta...............................................................................23
Operación de Sincronización..........................................................................26
Desconexión del Servicio...............................................................................27
Utilizar sesión de aplicación para acceder a webservice...............................27
Definir nuevas operaciones...............................................................................28
GetPDFdata....................................................................................................28
Totales de Facturación...................................................................................33
Crear ficheros de usuarios.............................................................................35
Librerías de Cliente............................................................................................36
Instalación..................................................................................................36
Requisitos...................................................................................................36
Librería Cliente PHP.......................................................................................36
Funcionalidades de la Clase.......................................................................37
doLogin......................................................................................................37
doListTypes................................................................................................38
doDescribe.................................................................................................38
doCreate....................................................................................................39
doRetrieve..................................................................................................39
doQuery.....................................................................................................40
doInvoke....................................................................................................40
lastError.....................................................................................................41
toJSON........................................................................................................41
toJSONString..............................................................................................42
Librería Cliente Javascript..............................................................................43
Funcionalidades de la Clase.......................................................................43
doLogin......................................................................................................43
Argumento Callback...............................................................................44
doListTypes................................................................................................45
doDescribe.................................................................................................45
doCreate....................................................................................................46
doRetrieve..................................................................................................46
doQuery.....................................................................................................47
doInvoke....................................................................................................47
lastError.....................................................................................................48
toJSON........................................................................................................49
toJSONString..............................................................................................49
Librería Cliente Java.......................................................................................49
Funcionalidades de la Clase.......................................................................50
doLogin......................................................................................................50
doListTypes................................................................................................51
doDescribe.................................................................................................51
doCreate....................................................................................................52
doRetrieve..................................................................................................53
doQuery.....................................................................................................53
doInvoke....................................................................................................54
lastError.....................................................................................................54
toJSON........................................................................................................55
toJSONString..............................................................................................55
Programa vtiger CRM Webservices Browser (vtwsbrowser)..............................56
Procedimiento de acceso a usuarios.................................................................58
Acceso al código de este libro...........................................................................58
Prólogo
Esta documentación describe el interfaz de programación de aplicaciones (API)
REST o webservice disponible en vtiger CRM. Se entiende como un documento
de referencia y aprendizaje para los consumidores del API. En su mayor parte
es la traducción de las páginas sobre este tema disponibles en el wiki de vtiger
crm y de las diversas conversaciones recogidas en foros y listas de correo y
nuestra propia experiencia en el uso de la misma. Formando así un punto único
de referencia sobre el tema tratado.
Además, contiene una relación de ejemplos y extensiones útiles para facilitar la
adquisición de conocimiento y soltura en el uso de este servicio.
Queremos agradecer todo el esfuerzo y tiempo que invierte el equipo de vtiger
en compartir este gran producto con el mundo.

-1-
Introducción
El protocolo REST define un sistema consistente y seguro para acceder a la
mayoría de las entidades de vtiger CRM. Permite un acceso directo a la base de
datos sin pasar por la aplicación que facilita las tareas de integración entre
esta aplicación y otras de distinta índole.
La implementación del protocolo realizada por vtiger CRM utiliza el formato
JSON para representar las estructuras de datos e intercambio de información
entre la aplicación final y vtiger CRM.
Cada entidad tiene un formato especial de identificación que se puede utilizar
para conocer su tipo y el registro concreto. La operación de crear es el único
caso en el que no se requiere una identificación de registro.

Formato de Llamada
Para acceder al servicio se llama siempre al mismo programa de la misma
manera indicando la operación y los parámetros necesarios en cada caso.
http://url_vtiger/webservice.php?operation=[tipo operación]&sessionName=[nombre
sesión]&[parámeteros específicos de la operación]

El funcionamiento general se basa en:


• REST - API está basado en el protocolo REST, así que toda la comunicación
entre cliente y servidor ocurre sobre HTTP como peticiones GET o POST.
• JSON - se utiliza el formato JSON para codificar las peticiones y las respuestas
• Peticiones y Respuestas - La aplicación cliente prepara y envía peticiones de
servicio al API, el API procesa la petición y devuelve una respuesta,
finalmente la aplicación cliente gestiona la respuesta .
• Cambios inmediatos - Cada operación que escribe a un objeto vtiger CRM se
guarda inmediatamente.

Formato de Respuesta
La respuesta a cualquier solicitud de servicio web es un objeto JSON. El objeto
tiene un campo de éxito que tendrá el valor verdadero (true) si la operación
fue un éxito y falso (false) en caso contrario. Si el resultado es falso el objeto
de respuesta contendrá un campo “error” que contendrá un objeto JSON. El
objeto de error contendrá dos campos code, una sola palabra describiendo el
error, y message, una cadena que contiene una descripción del error.
Por tanto, todas las respuestas de una ejecución, tendrán el siguiente formato.

-2-
Si la solicitud se procesa con éxito, entonces el formato es
Response{

success:Boolean=true

result:Object //El objeto respuesta

Si se produce un error procesando la petición,


Response{

success:Boolean=false

error:ErrorObject

donde
ErrorObject{

code:String //Representación del tipo de error

message:String //Mensaje de error devuelto

Operaciones
En esta versión, las operaciones definidas son:
• getchallenge: para obtener una clave de acceso al servicio, sin esto no
podemos acceder
• login: permite la validación del usuario en el servicio y la conexión al servicio
• create: crear nuevos registros
• retrieve: obtener información de registros
• update: actualizar registros
• delete: eliminar registros
• sync: permite la obtención de todos los cambios realizados desde la fecha
dada
• query: permite ejecutar cualquier consulta
• listtypes: obtiene una lista de módulos y campos disponibles
• describe: devuelve el conjunto de operaciones permitidas por el usuario
conectado
• logout: desconexión del servicio
• extendsession: permite utilizar la sesión definida al validarse en la
aplicación, de esta manera se puede acceder al servicio de manera
transparente una vez el usuario haya entrado en la aplicación de manera
normal

-3-
Nombre de Sesión
La clave que se utiliza para identificar la sesión actual. Esto debe ser enviada al
servidor como parte de cada solicitud.

Seguridad
El servicio REST soporta el modelo de seguridad seguido en la interfaz de
usuario vtiger CRM web, por lo que el usuario conectado solo podrá realizar
aquellas operaciones que podría hacer en la aplicación.
Para elevar la seguridad en el servicio expuesto, el proceso de inicio de sesión
utiliza un esquema en dos etapas desafío/respuesta.

Tipos de Datos utilizados

VtigerObject
Un mapa que representa el contenido de un objeto basado en crmentity. O sea,
el contenido de cualquier registro de la aplicación que esté basada en un
módulo o entidad.
Todos los campos de referencia se representa mediante el tipo de
identificación (<moduleid>'x'<recordid>).
Existe un campo especial, llamado Id, que posee el formato de un identificador
de entidad (<moduleid>'x'<recordid>), que es la clave de identificación de
única del objeto. Este campo está presente para cualquier objeto que se
obtenga de la base de datos.

Id Format
objectTypeId 'x' objectId
objectTypeId - Identificador del tipo de objeto o entidad (módulo). Este número
es generado unívocamente para cada entidad soportada por el API y puede ser
obtenida para un módulo utilizando la operación describe.

Map
Un array asociativo de pares de clave ⇒ valor. Normalmente se utiliza en
operación de creación.

TimeStamp
Un número entero largo representando el número de segundos desde Unix
Epoch.

-4-
GetChallengeResult
Un objeto que representa la respuesta de una operación getchallenge,
GetChallengeResult{

token:String //Clave de desafío del servidor.

serverTime:TimeStamp //La hora actual del servidor.

expireTime:TimeStamp //La hora que caduca la clave de desafío entregada.

LoginResult
Un objeto que representa la respuesta de una operación de validación (login),
LoginResult{

sessionId:String //Identificador unívoco de la sesión

userId:String //Identificador del usuario a validarse

version:String //La versión del servicio REST

vtigerVersion:String //La versión de vtiger CRM.

SyncResult
Un objeto que representa la respuesta de una operación de sincronización,
SyncResult{

updated:[Object] //Lista de Objetos creados o modificados.

deleted:[Id] //Lista de *Id* de objetos eliminados.

lastModifiedTime:Timstamp //fecha/hora del último cambio, que puede ser utilizado en la


siguiente llamada para obtener los nuevos cambios

-5-
Operaciones
Get Challenge
Propósito: Obtiene una clave de desafío para poder realizar el acceso al servicio
Perfil: getchallenge(username:String):GetChallengeResult
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros: username: nombre de usuario dado de alta y activo en vtiger CRM
Respuesta: Un objeto GetChallengeResult con la clave de desafío del servidor
Formato URL: http://vtiger_url/webservice.php?
operation=getchallenge&username=[username]

Login
Propósito: Validar el acceso del usuario en el servicio. Es necesario utilizar la clave de
desafío obtenida con la operación getchallenge
Perfil: login(username:String, accessKey:String):LoginResult
Tipo envío: POST (obligatorio, no puede ser GET)
Parámetros: username: nombre de usuario dado de alta y activo en vtiger CRM
accessKey: una cadena md5 resultante de la concatenación de la clave de
desafío y la clave de acceso del usuario
Respuesta: Un objeto LoginResult con el identificador de la sesión, la versión del API y el
identificador del usuario
Formato URL: http://vtiger_url/webservice.php?
operation=login&username=[username]&accessKey=[accessKey]
Comentarios: El parámetro accessKey se escribe con 'K' mayúscula
La clave de acceso del usuario se obtiene en su página de preferencias:

Clave de Acceso

Create
Propósito: Crear un nuevo registro en la aplicación
Perfil: create(element:Map, elementType:String): VtigerObject
Tipo envío: POST (obligatorio, no puede ser GET)
Parámetros: element: Campos del objeto a crear. Valores para los campos obligatorios han
de estar presentes
elementType: El nombre de la entidad/módulo a crear
Respuesta: Un objeto VtigerObject con todos los datos del nuevo registro creado
Formato URL: http://vtiger_url/webservice.php?operation=create&sessionName=[session
id]&element=[object]&elementType=[object type]

-6-
Retrieve
Propósito: Obtener todos los valores de un registro en la aplicación
Perfil: retrieve(id: Id): VtigerObject
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros: id: El identificador del registro en el formato de identificador
Respuesta: Un objeto VtigerObject con todos los datos del registro encontrado
Formato URL: http://vtiger_url/webservice.php?operation=retrieve&session_name=[session
id]&id=[object id]

Update
Propósito: Actualizar TODOS los campos de un registro en la aplicación
Perfil: update(object: VtigerObject): VtigerObject
Tipo envío: POST (obligatorio, no puede ser GET)
Parámetros: object: El VtigerObject a actualizar
Respuesta: Un objeto VtigerObject con todos los datos del registro después de la
actualización
Formato URL: http://vtiger_url/webservice.php?operation=update&sessionName=[session
id]&element=[object]

Delete
Propósito: Eliminar un registro de la aplicación
Perfil: delete(id:Id):Map
Tipo envío: POST (obligatorio, no puede ser GET)
Parámetros: id: El identificador del objeto a eliminar
Respuesta: Un objeto Map con un solo valor 'successfull'
Formato URL: http://vtiger_url/webservice.php?operation=delete&sessionName=[session
id]&id=[object id]

Query
Propósito: Esta operación permite realizar consultas sobre la información contenida en
la aplicación
Perfil: query(queryString : String): [VtigerObject]
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros: queryString: La consulta a procesar
Respuesta: Un objeto Map con las filas y columnas obtenidas como resultado de la
consulta
Formato URL: http://vtiger_url/webservice.php?operation=query&sessionName=[session
id]&query=[query string]

vtiger crm REST proporciona un lenguaje de consulta sencillo para obtener


datos. Este lenguaje es muy similar al soportado por el comando SELECT en
SQL pero tiene limitaciones:
• las consultas están limitadas a una única entidad/módulo, no se permiten
uniones entre entidades
• solo se permite hacer consultas sobre entidades, no sobre cualquier tabla de
la base de datos

-7-
• no se soportan consultas embebidas
• no se soportan agrupaciones ni agregaciones salvo contar los elementos
• el resultado está restringido a 100 registros, la aplicación cliente puede usar
el operador limite para obtener registros diferentes
Aun con ello, sigue siendo una forma eficaz de obtener datos de vtiger CRM.
El formato de consulta es:
select * | <column_list> | <count(*)>
from <object> [where <conditionals>]
[order by <column_list>] [limit [<m>, ]<n>];

• column_list: lista de campos separados por comas


• count(*), devuelve el número de elementos que cumplen la condición en la
entidad
• object: nombre de la entidad a consultar
• conditionals: operaciones de condición o cláusulas “en” (in) o clausulas
“como” (like) separadas por operadores 'and' o 'or'. Estas condiciones se
procesan de izquierda a derecha.
• conditional operators:
<, >, <=, >=, =, !=

• in clauses: <column name> in (<value list>)


• value list: lista de valores separados por comas
• like clauses: like 'sqlregex'
• el parámetro <column_list> en la cláusula order by está limitado a dos
columnas
• m, n: valores enteros que especifican el desplazamiento y el límite de
registros devueltos

Sync
Propósito: Devuelve un objeto SyncResult que contiene todos los cambios surgidos en la
aplicación desde modifiedTime
Perfil: sync(modifiedTime: Timestamp, elementType: String):SyncResult
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros: modifiedTime: Una fecha/hora de la última sincronización
elementType: parámetro opcional, nombre de módulo del que deseamos
obtener los cambios, si no se especifica se devuelve los cambios de todos los
módulos a los que tiene acceso el usuario validado
Respuesta: Un objeto SyncResult con los cambios
Formato URL: http://vtiger_url/webservice.php?operation=sync&sessionName=[session
id]&modifiedTime=[timestamp]&elementType=[elementType]

-8-
Logout
Propósito: Desconectar del servicio, elimina la sesión y la invalida para el uso
Perfil: logout(): Map
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros:
Respuesta: Un objeto Map con un único valor 'successfull'
Formato URL: http://vtiger_url/webservice.php?operation=logout&sessionName=[session id]

List Types
Propósito: Lista el nombre de todos los objetos vtiger crm disponibles en el servicio
Perfil: listtypes(): Map
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros:
Respuesta: Un objeto Map con una clave 'types' que contiene una lista de nombres de
objetos vtiger CRM
Formato URL: http://vtiger_url/webservice.php?operation=listtypes&sessionName=[session
id]

Describe
Propósito: Devuelve el conjunto de operaciones permitidas por el usuario conectado
sobre el objeto pedido
Perfil: describe(elementType: String): DescribeResult
Tipo envío: GET (obligatorio, no puede ser POST)
Parámetros: elementType: el nombre del módulo del que se quiere la descripción
Respuesta: Un objeto DescribeResult (ver a continuación) con la información del módulo
Formato URL: http://vtiger_url/webservice.php?
operation=describeobject&sessionName=[session
id]&elementType=[elementType]

El objeto devuelto por esta operación contiene estos campos:


1. label - etiqueta correspondiente al nombre del módulo.
2. name - el nombre del módulo.
3. createable - valor booleano indicando si el usuario conectado puede crear
registros.
4. updateable - valor booleano indicando si el usuario conectado puede
actualizar registros.
5. deleteable - valor booleano indicando si el usuario conectado puede
eliminar registros.
6. retrieveable - valor booleano indicando si el usuario conectado puede
obtener (consultar) registros.
7. fields - un array que contiene los nombres de los campos disponibles y toda
su información sobre su tipo.

-9-
Cada elemento en el array de campos describe un campo en particular en el
módulo.
1. name - el nombre del campo utilizado internamente por vtiger crm.
2. label - la etiqueta utilizada para mostrar el campo.
3. mandatory - valor booleano que indica si el campo es obligatorio, los
campos obligatorios han de estar presentes a la hora de creación.
4. type - un array que describe el tipo de información contenida en el campo.
5. default - el valor por defecto del campo.
6. nillable - valor booleano indicando si el campo puede ser nulo/vacío.
7. editable - valor booleano indicando si el campo puede ser modificado.

El elemento type tiene importancia especial ya que describe el contenido de un


campo. Es un array que contiene, al menos, un elemento denominado name
que es el nombre del tipo de dato. El tipo puede ser:
1. string - una única línea de texto
2. text - un texto de varias líneas
3. integer - un número sin decimales
4. double - un número con decimales
5. boolean - campo lógico/booleano, contiene verdadero o falso
6. time - una cadena con el formato hh:mm, el formato se basa en las
preferencias del usuario
7. date - un array con dos elementos, una cadena que representa una fecha y
otro elemento con el formato en el que se espera el valor, se basa en las
preferencias del usuario conectado
8. datetime - un array con dos elementos, una cadena que representa una
fecha y hora, y otro elemento con el formato en el que se espera el valor, se
basa en las preferencias del usuario conectado
9. autogenerated - Estos son los campos cuyos valores son generados
automáticamente por vtiger CRM, estos suelen ser campos identificadores
de un objeto
10. reference - Un campo que muestra una relación con otro objeto, el array
contendrá, además, otro elemento llamado refersTo que es una matriz que
contiene el nombre de los módulos con los que puede relacionarse
11. picklist - Un campo que puede contener una lista de valores, el array
contendrá dos elementos, picklistValues que es una lista de valores
posibles, y defaultValue que es el valor por defecto de la lista
12. multipicklist - Un campo picklist en el que se puede seleccionar varios
valores
13. phone - un campo para almacenar teléfonos
14. email - un campo para almacenar identificadores de email

- 10 -
15. url - un campo para almacenar urls
16. skype - un campo para almacenar teléfonos o identificadores skype
17. password - un campo para almacenar contraseñas
18. owner - Un campo para definir el propietario del registro. Podría ser un
grupo o usuario individual

Extend Session
Propósito: Permite utilizar la sesión definida al validarse en la aplicación, de esta manera
se puede acceder al servicio de manera transparente una vez el usuario haya
entrado en la aplicación de manera normal. Cabe destacar que ambas
sesiones quedan ligadas por lo que hacer una desconexión de una invalidará
automáticamente la otra.
Perfil: extendsession(username:String):LoginResult
Tipo envío: POST (obligatorio, no puede ser GET)
Parámetros: username: nombre de usuario vtiger crm
Respuesta: Un objeto LoginResult con el identificador de la sesión
Formato URL: http://vtiger_url/webservice.php?operation=extendsession

Entidades CRM
Lista de Entidades CRM expuestas por el servicio.
Nombre Descripción
Calendario El módulo de calendario gestiona los eventos, reuniones y tareas.
Eventos El módulo de Eventos gestiona eventos y reuniones, no tareas.
PreContactos El módulo de PreContactos sirve para gestionar información de
potenciales clientes.
Cuentas El módulo de Cuentas representa las empresas con las que trabajas.
Contactos El módulo de Contactos representa personas con las que trabajamos,
posiblemente dentro de las empresas.
Oportunidades El módulo de Oportunidades gestionas las oportunidades de negocio que
tenemos con nuestros clientes.
Productos El módulo de Productos gestiona los bienes que vende nuestra empresa.
Documentos El módulo de Documentos gestiona la base de documentos y notas
Carpetas Documento Las carpetas de Documentos nos permiten agrupar documentos.
Emails El módulo de Emails registra los emails enviados y recibidos clientes.
Incidencias El módulo de Incidencias registra los problemas y/o preguntas que nos
hacen los clientes sobre nuestros servicios.
Faq El módulo de FAQ gestionar la base de conocimiento de la empresa.
Proveedores El módulo de Proveedores sirve para gestionar los proveedores
Tarifas Las tarifas gestionan los precios de nuestros productos.
Presupuestos El módulo de Presupuestos gestiona las ofertas que hacemos a clientes.
Orden Compra El módulo de Ordenes de Compra registra las compras que hacemos
Orden Venta El módulo de Ordenes de Venta registra los pedidos recibidos
Factura El módulo de Facturas gestiona las facturas que emitimos.
Campañas El módulo de Campañas registra los eventos de Marketing.
Usuarios El módulo de Usuarios administra los usuarios del sistema.
Grupos El módulo de Grupos relaciona usuarios entre sí.

- 11 -
Moneda El módulo de Monedas permite definir diferentes monedas y su
conversión respecto a la moneda base. Estas monedas se pueden
utilizar en los módulos de inventario para dar soporte a funcionalidades
de multi-moneda.

Tipos de campos
picklist
Descripción: Un campo que puede contener una lista de valores, el array
contendrá dos elementos, picklistValues que es una lista de valores posibles, y
defaultValue que es el valor por defecto de la lista.
Nombre Descripción
picklistValues Una lista de posibles valores.
defaultValue Especifica qué valor es el valor por defecto de la lista.
name Nombre del campo

multipicklist
Descripción: Un campo picklist en el que se puede seleccionar varios valores.

reference
Descripción: Un campo que muestra una relación con otro objeto, el array
contendrá, además, otro elemento llamado refersTo que es una matriz que
contiene el nombre de los módulos con los que puede relacionarse.
Nombre Descripción
refersTo Una lista de nombres de módulos con los que se puede
relacionar este campo.
name Nombre del campo

datetime
Descripción: Una cadena que representa una fecha y hora, el formato se basa
en el formato de fecha del usuario en su configuración.

date
Descripción: Una cadena que representa una fecha, el array contendrá,
además, otro elemento llamado format que es el formato en el que se espera
que esté el valor de este campo. Se basa en el formato de fecha del usuario en
su configuración.
Nombre Descripción
format formato en el que se espera que esté el valor de este campo.
name Nombre del campo

- 12 -
time
Descripción: Una cadena en formato hh:mm. Se basa en el formato de fecha
del usuario en su configuración.

string
Descripción: Una cadena de texto de una sola línea.

text
Descripción: Una cadena de texto multilínea.

password
Descripción: Una cadena de texto para almacenar contraseñas.

boolean
Descripción: Una campo lógico que puede contener los valores verdadero
(true) o falso (false).

integer
Descripción: Un campo numérico sin decimales.

double
Descripción: Un campo numérico con decimales.

decimal
Descripción: Un campo numérico con decimales de coma flotante.

owner
Descripción: Un campo para definir el propietario del registro. Podría ser un
grupo o usuario individual.

autogenerated
Descripción: Estos son los campos cuyos valores son generados
automáticamente por vtiger CRM, estos suelen ser campos identificadores de
un objeto.

email
Descripción: Un campo que almacena identificadores de email.

- 13 -
phone
Descripción: Un campo que almacena números de teléfono.

skype
Descripción: Un campo que almacena números de teléfono o identificadores
SKYPE.

url
Descripción: Un campo que almacena un hipervínculo.

file
Descripción: Una campo para añadir ficheros a vtiger CRM.
Nombre Descripción
maxUploadFileSize Tamaño máximo permitido para el fichero que se manda.
name Nombre del campo

Problemas conocidos
• Sync no funciona sobre el módulo de usuarios ni con módulos que no sean
entidades como Moneda, Grupos, etc.

• La sintaxis de Consulta tiene limitaciones.

• Si las llamadas a las operaciones son muy seguidas, el servicio puede


producir errores y detenerse. Esto ocurre especialmente al intentar realizar
importaciones o sincronizaciones masivas de golpe. Como solución he visto
varias aproximaciones, básicamente consistentes en colocar una capa entre
las llamadas a las operaciones y el propio servicio que hace un balanceo de
la carga para que vtiger CRM no se sature. La mejor opción para esto es la
utilización de Jolie (wsdl2jolie). También existe este ticket en el trac de vtiger
referente a este asunto. El error recibido suele ser este:
Invalid use of SingleClientConnManager: connection still allocated. Make sure to
release the connection before allocating another one.

• En ocasiones, cuando nos conectamos a vtiger CRM usando el cliente para


Java vtwsclib, obtenemos el siguiente mensaje de error:

{"message":"Invalid username or password","code":"INVALID_USER_CREDENTIALS"}

- 14 -
Por lo que he podido comprobar, cuando el cliente se conecta, usando el
usuario admin, coge el token de seguridad de sesión y una vez logeado,
dentro del cliente java, comprueba si ese token ha expirado. Pues en ese
periodo de tiempo, justo en el momento de la comprobación, el token cambia
y muestra ese mensaje. Además he visto que esto pasa incluso cuando existe
un token de sesión válido. Una posible solución podría ser:

Index: include/Webservices/AuthToken.php
===================================================================
--- include/Webservices/AuthToken.php (revisión: 3711)
+++ include/Webservices/AuthToken.php (copia de trabajo)
@@ -18,6 +18,14 @@

$servertime = time();
$expireTime = time()+(60*5);
+ $sql = "select userid,token,expiretime,count(*) as count from
vtiger_ws_userauthtoken where userid=? and expiretime>? group by userid";
+ $res = $adb->pquery($sql,array($userid,$servertime));
+ $result = $adb->fetchByAssoc($res);
+ if ($result['count']>=1) {
+ $sql = "update vtiger_ws_userauthtoken set expireTime = ? where userid
= ?";
+ $adb->pquery($sql,array($expireTime, $userid));
+ return
array("token"=>$result["token"],"serverTime"=>$servertime,"expireTime"=>$result["expir
etime"]);
+ }

$sql = "delete from vtiger_ws_userauthtoken where userid=?";


$adb->pquery($sql,array($userid));

- 15 -
Tutorial vtiger CRM Webservices
Requerimientos
El código del tutorial está escrito en PHP y tiene dos dependencias sobre las
librerías Zend Json y Http_Client.
Para poder ejecutar el código del tutorial, será necesario disponer de:
• Una instalación de vtiger CRM con soporte de webservices.
• Un servidor Apache/PHP para ejecutar el código de ejemplo.
• La librería HTTP_Client que puede instalarse con el comando pear:
pear install HTTP_Client

• La librería Zend JSON, se puede descargar el minimal zend framework


• Todo el código del tutorial se puede obtener online

Accediendo al Sistema
La API no utiliza la contraseña del usuario para entrar. En su lugar, vtiger CRM
proporciona una clave de acceso única para cada usuario. Para obtener la clave
de un usuario, vaya al panel de Mis Preferencias de ese usuario y encontrarás
el campo de clave de acceso.

Clave de Acceso

La operación de Login inicia una sesión de cliente con el servidor, autentifica el


usuario y devuelve un sessionId que se utilizará para toda la comunicación
posterior con el servidor.

El inicio de sesión es un proceso de dos pasos, en el primero, el cliente obtiene


la clave de desafío del servidor, en el segundo se mezcla la clave de desafío y
la clave de acceso del usuario para acceder al servicio.

- 16 -
Get Challenge
La operación Get Challenge nos permitirá obtener una clave de desafío como
se ve en el siguiente ejemplo.
<?php
require_once 'HTTP/Client.php';
require_once 'Zend/Json.php';
require_once 'debugoutput.php';

// Debug messages
$dcall=$_REQUEST['directcall'];
//url path to vtiger/webservice.php like http://vtiger_url/webservice.php
$endpointUrl = "http://localhost/ts521devel2/webservice.php";
//username of the user who is to logged in.
$userName="admin";

$httpc = new HTTP_Client();


//getchallenge request must be a GET request.
$httpc->get("$endpointUrl?operation=getchallenge&username=$userName");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json)",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response",$jsonResponse);

//check for whether the requested operation was successful or not.


if($jsonResponse['success']==false)
//handle the failure case.
die('getchallenge failed: '.$jsonResponse['error']['message']);

//operation was successful get the token from the reponse.


$challengeToken = $jsonResponse['result']['token'];
if ($dcall==1) printvar("Challenge token",$challengeToken);
?>

- 17 -
Login
Ahora que tenemos la clave de desafío podemos proceder con la operación de
Login. La clave de acceso necesaria es el resultado del cálculo de un MD5
sobre la concatenación de la calve de desafío y la clave de acceso del usuario.
Esta operación se ejecuta como POST.
Podremos acceder al servicio utilizando la clave de desafío obtenida en el paso
anterior con este código.
<?php
include 'getchallenge.php';

//access key of the user admin, found on my preferences page.


$userAccessKey = 'dPMo3wuNJoWv3Y8U';

//create md5 string concatenating user accesskey from my preference page


//and the challenge token obtained from get challenge result.
$generatedKey = md5($challengeToken.$userAccessKey);
//login request must be POST request.
$httpc->post("$endpointUrl",
array('operation'=>'login', 'username'=>$userName,
'accessKey'=>$generatedKey), true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) doLogin",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response doLogin",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('login failed: '.$jsonResponse['error']['message']);

//login successful extract sessionId and userId from LoginResult to it can used for
further calls.
$sessionId = $jsonResponse['result']['sessionName'];
$userId = $jsonResponse['result']['userId'];

if ($dcall==1) printvar("doLogin sessionId",$sessionId);

?>

- 18 -
Obteniendo Información de los Objetos
El servicio soporta dos operaciones para obtener información sobre los objetos
vtiger CRM.

List Types
La operación List Types proporciona una lista de módulos disponibles. Esta lista
sólo contiene los módulos a los que tiene acceso el usuario registrado.
El resultado es un array con un único valor “types” que contiene todos los
módulos accesibles.
<?php
require 'dologin.php';

//listtypes request must be GET request.


$httpc->get("$endpointUrl?sessionName=$sessionId&operation=listtypes");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) listtypes",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response listtypes",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('list types failed: '.$jsonResponse['error']['message']);
//Get the List of all the modules accessible.
$modules = $jsonResponse['result']['types'];
echo "<b>Accesible Modules</b><br>";
foreach ($modules as $modname) {
echo "$modname<br>";
}
?>

Describe
La operación Describe proporciona información detallada de un módulo, tanto
sobre las operaciones que podemos hacer sobre la entidad como todos los
detalles de los campos a los que tiene acceso el usuario registrado.
A continuación vemos el código necesario para consultar toda la información
del módulo de Contactos.
<?php
require 'dologin.php';

//vtiger Object name which need be described or whose information is requested.


// Can be passed in with modulename parameter
$moduleName=(empty($_REQUEST['modulename']) ? 'Contacts' : $_REQUEST['modulename']);
//use sessionId created at the time of login.
$params = "sessionName=$sessionId&operation=describe&elementType=$moduleName";
//describe request must be GET request.
$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) describe",$response);
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response describe",$jsonResponse);

- 19 -
//operation was successful get the token from the reponse.
if($jsonResponse['success']==false)
//handle the failure case.
die('describe object failed: '.$jsonResponse['error']['message']);
//get describe result object.
$description = $jsonResponse['result'];
var_dump($description);
?>

El objeto devuelto por esta operación se puede consultar aquí.

Operaciones de cambio en la aplicación (CRUD)


El API proporciona operaciones para crear, recuperar, actualizar y eliminar
objetos de la aplicación.

Crear
Crea un nuevo registro en la aplicación.

Ejemplo 1
El siguiente ejemplo crea un contacto utilizando la operación de Create, en
este caso los campos obligatorios son lastname y assigned_user_id. El valor
devuelto $savedObject es un array que contiene los campos del nuevo objeto
creado, incluyendo un identificador que se puede utilizar para identificar el
nuevo registro.
<?php
require 'dologin.php';

//fill in the details of the contacts.userId is obtained from loginResult.


$contactData = array('lastname'=>'Valiant',
'assigned_user_id'=>$userId,'homephone'=>'123456789');
//encode the object in JSON format to communicate with the server.
$objectJson = Zend_JSON::encode($contactData);
if ($dcall==1) printvar("Create, sending in",$objectJson);

//name of the module for which the entry has to be created.


$moduleName = 'Contacts';

//sessionId is obtained from loginResult.


$params = array("sessionName"=>$sessionId, "operation"=>'create',
"element"=>$objectJson, "elementType"=>$moduleName);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Create",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Create",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('create failed: '.$jsonResponse['error']['message']);
$savedObject = $jsonResponse['result'];
$id = $savedObject['id'];
var_dump($savedObject);
?>

- 20 -
Ejemplo 2
Crear un contacto y asociar con una cuenta. Para realizar esta tarea basta con
conocer el identificador de la cuenta y establecer este valor en el campo
correspondiente en el contacto. Para poder obtener el identificador disponemos
de la operación Query (ver ejemplos). Para este ejemplo vamos a suponer que
hemos ejecutado esta operación para obtener el identificador de la cuenta con
nombre vtiger y hemos obtenido 3×2.
<?php
require 'dologin.php';

//Create a Contact and associate with an existing Account.


// To obtain the identifier of the account you can use the Query operation
$accountId = '3x2';

//fill in the details of the contacts.userId is obtained from loginResult.


$contactData = array('lastname'=>'CtoWithAccount',
'assigned_user_id'=>$userId,'homephone'=>'123456789','account_id'=>$accountId);
//encode the object in JSON format to communicate with the server.
$objectJson = Zend_JSON::encode($contactData);
if ($dcall==1) printvar("Create, sending in",$objectJson);

//name of the module for which the entry has to be created.


$moduleName = 'Contacts';

//sessionId is obtained from loginResult.


$params = array("sessionName"=>$sessionId, "operation"=>'create',
"element"=>$objectJson, "elementType"=>$moduleName);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Create",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Create",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('create failed: '.$jsonResponse['error']['message']);
$savedObject = $jsonResponse['result'];
$id = $savedObject['id'];
var_dump($savedObject);
?>

Obtener
Obtener los valores de un registro existente en la aplicación. Podemos
recuperar un objeto utilizando su identificador y la operación de Retrieve. Esta
operación nos devuelve una array con todos los campos leídos. Los campos de
tipo referencia contiene un identificador de objeto y siempre habrá un campo
especial Id que será el identificador de objeto del registro recuperado.
En el ejemplo recuperamos el objeto con identificador 3×2.
<?php
require 'dologin.php';

// To obtain the identifier of the account you can use the Query operation
$accountId = '3x2';

- 21 -
//sessionId is obtained from loginResult.
$params = "sessionName=$sessionId&operation=retrieve&id=$accountId";
//Retrieve must be GET Request.
$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Create",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Create",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('retrieve failed: '.$jsonResponse['error']['message']);

$retrievedObject = $jsonResponse['result'];
var_dump($retrievedObject);
?>

Actualizar
Actualiza todos los campos de un registro. No permite actualizar solo uno
campos sueltos, para hacer esto sería necesario primero recuperar el registro,
después modificar los campos pertinentes y volver a guardar el registro entero.
En el siguiente ejemplo, actualizamos el registro de Contactos creado en el
ejemplo de creación. En ese ejemplo, en la secuencia que estoy ejecutando el
desarrollo de los ejemplos y en la instalación de prueba que tengo, se ha
asignado al contacto el identificador 4×194. Una prueba interesante es editar
unos campos de este registro dentro de la aplicación y verificar como se
pierden esos valores tras la ejecución del siguiente ejemplo.
<?php
require 'dologin.php';

// Obtained from contact creation example


$contactId='4x194';

//fill in the details of the contacts.userId is obtained from loginResult.


$contactData = array('lastname'=>'Valiant Update',
'assigned_user_id'=>$userId,'homephone'=>'987654321','id'=>$contactId);
//encode the object in JSON format to communicate with the server.
$objectJson = Zend_JSON::encode($contactData);
if ($dcall==1) printvar("Update, sending in",$objectJson);

//name of the module for which the entry has to be created.


$moduleName = 'Contacts';

//sessionId is obtained from loginResult.


$params = array("sessionName"=>$sessionId, "operation"=>'update',
"element"=>$objectJson, "elementType"=>$moduleName);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Update",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Update",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.

- 22 -
die('create failed: '.$jsonResponse['error']['message']);
$savedObject = $jsonResponse['result'];
$id = $savedObject['id'];
var_dump($savedObject);
?>

Eliminar
Con la operación de Delete se puede eliminar cualquier registro al que
tenemos acceso. Esta operación no devuelve ningún resultado salvo el
estandar indicando si se ha podido eliminar o no el registro indicado.
<?php
require 'dologin.php';

// Obtained from contact creation example


$contactId='4x194';

//delete a record created in above examples, sessionId a obtain from the login result.
$params = array("sessionName"=>$sessionId, "operation"=>'delete', "id"=>$contactId);
//delete operation request must be POST request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Delete",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Delete",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('delete failed: '.$jsonResponse['error']['message']);

printvar("Record Deleted",$jsonResponse);
?>

Operaciones de Consulta
La operación de Consulta permite interrogar la aplicación en busca de
información. La sintaxis soportado por esta operación es definida por vtiger y
se basa en las reglas de SQL sin ser tan potente. Se puede ver las opciones y
limitaciones del lenguaje de consulta en la sección operación de Consulta.
El primer ejemplo obtiene todos los contactos a los que tiene acceso el usuario
conectado.
<?php
require 'dologin.php';

//query to select data from the server.


$query = "select * from Contacts;";
//urlencode to as its sent over http.
$queryParam = urlencode($query);
//sessionId is obtained from login result.
$params = "sessionName=$sessionId&operation=query&query=$queryParam";
//query must be GET Request.
$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Query",$response);

- 23 -
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Query",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('query failed: '.$jsonResponse['message']);

//Array of vtigerObjects
$retrievedObjects = $jsonResponse['result'];
if (count($retrievedObjects)>0) {
echo "<table border=1><tr>";
foreach ($retrievedObjects[0] as $key=>$value) {
echo "<th>$key</th>";
}
echo "</tr>";
foreach ($retrievedObjects as $record) {
echo "<tr>";
foreach ($record as $value) {
echo "<td>&nbsp;$value</td>";
}
echo "</tr>";
}
echo "</table>";
} else {
echo "No records found!";
}
?>

El siguiente ejemplo aplica un condicional a la consulta y obtiene aquellos


contactos con apellido “Valiant”.
<?php
require 'dologin.php';

//query to select data from the server.


$query = "select * from Contacts where lastname='Valiant';";
//urlencode to as its sent over http.
$queryParam = urlencode($query);
//sessionId is obtained from login result.
$params = "sessionName=$sessionId&operation=query&query=$queryParam";
//query must be GET Request.
$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Query",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Query",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('query failed: '.$jsonResponse['message']);

//Array of vtigerObjects
$retrievedObjects = $jsonResponse['result'];
if (count($retrievedObjects)>0) {
echo "<table border=1><tr>";
foreach ($retrievedObjects[0] as $key=>$value) {
echo "<th>$key</th>";
}
echo "</tr>";
foreach ($retrievedObjects as $record) {
echo "<tr>";
foreach ($record as $value) {
echo "<td>&nbsp;$value</td>";

- 24 -
}
echo "</tr>";
}
echo "</table>";
} else {
echo "No records found!";
}
?>

El último ejemplo saca un subconjunto de columnas.


<?php
require 'dologin.php';

//query to select data from the server.


$query = "select lastname,firstname,account_id,assigned_user_id from Contacts;";
//urlencode to as its sent over http.
$queryParam = urlencode($query);
//sessionId is obtained from login result.
$params = "sessionName=$sessionId&operation=query&query=$queryParam";
//query must be GET Request.
$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Query",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Query",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('query failed: '.$jsonResponse['message']);

//Array of vtigerObjects
$retrievedObjects = $jsonResponse['result'];
if (count($retrievedObjects)>0) {
echo "<table border=1><tr>";
foreach ($retrievedObjects[0] as $key=>$value) {
echo "<th>$key</th>";
}
echo "</tr>";
foreach ($retrievedObjects as $record) {
echo "<tr>";
foreach ($record as $value) {
echo "<td>&nbsp;$value</td>";
}
echo "</tr>";
}
echo "</table>";
} else {
echo "No records found!";
}
?>

- 25 -
Operación de Sincronización
La operación de Sincronización permite obtener el conjunto de cambios
acaecidos en la aplicación desde una fecha y hora dada.
<?php
require 'dologin.php';

//time after which all the changes on the server are needed.
$stime = time();
//Create some data now so it is captured by the sync api response.
//Create Account.
//fill in the details of the Accounts.userId is obtained from loginResult.
$accountData = array('accountname'=>'VtigerWsTest', 'assigned_user_id'=>$userId);
//encode the object in JSON format to communicate with the server.
$objectJson = Zend_JSON::encode($accountData);
//name of the module for which the entry has to be created.
$moduleName = 'Accounts';

//sessionId is obtained from loginResult.


$params = array("sessionName"=>$sessionId, "operation"=>'create',
"element"=>$objectJson, "elementType"=>$moduleName);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('create failed: '.$jsonResponse['error']['message']);
$createResult = $jsonResponse['result'];

$params = "operation=sync&modifiedTime=$stime&sessionName=$sessionId";

//sync must be GET Request.


$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Sync",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Sync",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('query failed: '.$jsonResponse['message']);

//Array of vtigerObjects
$retrievedObjects = $jsonResponse['result'];
printvar("Webservice Sync",$retrievedObjects);
?>

- 26 -
Desconexión del Servicio
La operación de Logout permite eliminar los datos de la sesión, invalidando
cualquier operación posterior con esta conexión.
<?php
require 'dologin.php';

//SessionId is the session which is to be terminated.


$params = "operation=logout&sessionName=$sessionId";

//logout must be GET Request.


$httpc->get("$endpointUrl?$params");
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) Logout",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response Logout",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('query failed: '.$jsonResponse['message']);

printvar("Webservice Logout",$jsonResponse);
?>

Utilizar sesión de aplicación para acceder a


webservice
La operación de Extend Session permite crear una sesión de acceso al servicio
de webservice utilizando la sesión existente al acceder a vtiger CRM de manera
normal. De esta manera podemos conectar a la aplicación sin pedir de nuevo
los datos de acceso cuando un usuario ya está conectado en la aplicación.
Cabe destacar que ambas sesiones quedan ligadas por lo que hacer una
desconexión de una invalidará automáticamente la otra.
El siguiente ejemplo está escrito en javascript ya que solo tiene sentido
ejecutar esta operación desde el entorno de un navegador. Será necesario
tener acceso a una librería AJAX (JQUERY) y JSON (json2.js file available with
vtiger at json.org).
//operation parameters.
var params = "operation=extendsession";
//end point of the services.
var endPointUrl = "http://vtiger_url/webservice.php";
//extendSession is post request, invoke jquery http post request.
$.post(endPointUrl, params, function(result){
//decode the json encode response from the server.
var jsonResponse = json.parse(result);
//operation was successful get the token from the reponse.
if(jsonResponse['success']==false)
//handle the failure case.
die('login failed: '+jsonResponse['error']['message']);
//login successful extract sessionId and userId from LoginResult so it can used for
further calls.
var sessionId = jsonResponse['result']['sessionName'];
var userId = jsonResponse['result']['userId'];
});

- 27 -
Definir nuevas operaciones
Este punto está basado en el aporte de David VALMINOS (12/11/2009) titulado:
”How To Create A New Webservice in Vtiger (GetPDFdata)”
En vez de simplemente mostrar los pasos necesarios para crear una nueva
operación aprovecharemos y crearemos una nueva operación haciendo
hincapié en los pasos importantes. Después mostraremos algunos ejemplos y
extensiones adicionales.

GetPDFdata
El portal del cliente de vtiger CRM utiliza el protocolo SOAP para comunicar con
la aplicación. Uno de los servicios disponibles es la obtención de la factura en
formato PDF. Para ello, el proceso seguido es de generar el PDF en el disco y
después mandarlo directamente al ordenador del solicitante.

Para la nueva operación webservice utilizaremos un proceso distinto:


capturaremos el contenido del PDF en una variable y mandaremos el contenido
de esta variable al programa cliente (en este caso Joomla) que será el
encargado de mandarlo al usuario.
Los pasos a seguir para añadir esta nueva operación son:

Paso 1: Hacer cambios en la base de datos. Las operaciones disponibles en


webservice se recogen en una tabla de la base de datos, por tanto, tendremos
que registrar nuestra nueva operación en esta tabla. La tabla es
vtiger_ws_operation y tenemos que definir los siguientes campos:

name El nombre de la operación. Nombre con el que será llamado desde el


interfaz
handler_patch El camino en el disco, relativo a la raíz de vtiger CRM, donde se encuentra
el código que implementa la operación. Todas las operaciones actuales se
encuentran en el directorio include/Webservices
handler_method La función o método principal de la operación. Esta será la que se llamará
al invocar la operación
type GET o POST
prelogin 0 si ha de existir una sesión para acceder a la operación, 1 si no lo es (por
ejemplo la operación de login)
operationid este campo está sincronizado con la tabla vtiger_ws_operation_seq.
Debemos incrementar el valor de esta tabla y asignar el nuevo valor a
nuestra operación

- 28 -
--
-- Increment operation sequence
--
update vtiger_ws_operation_seq set id=id+1;

--
-- Insert webservice entry in operation table
--
INSERT INTO `vtiger_ws_operation` (
`operationid`,
`name` ,
`handler_path` ,
`handler_method` ,
`type` ,
`prelogin`
)
VALUES (
(select max(id) from vtiger_ws_operation_seq),'getpdfdata',
'include/Webservices/GetPDFdata.php', 'vtws_getpdfdata', 'POST', '0'
);

Además, hay otra tabla vinculada con esta que también tenemos que modificar
si procede. La tabla vtiger_ws_operation_parameters define los parámetros que
tiene cada operación. En nuestro caso necesitamos un único parámetro que
indica el crmid de la factura de la cual queremos obtener su PDF. Cómo en el
caso anterior necesitamos obtener el operationid asignado para vincular la
operación con sus parámetros.

--
-- Insert one entry for each service's parameter
--
INSERT INTO `vtiger_ws_operation_parameters` (
`operationid` ,
`name` ,
`type` ,
`sequence`
)
VALUES (
(select max(id) from vtiger_ws_operation_seq), 'id', 'string', '0'
);

Paso 2: Crear el código que implementa la operación en el fichero y camino


indicado además de cualquier cambio necesario en la aplicación principal para
apoyar el funcionamiento de la nueva operación. En este caso hemos de hacer
dos cosas:
• copiar el siguiente programa a include/Webservices/GetPDFdata.php
<?php
/************************************************************************************
* The contents of this file are subject to the vtiger CRM Public License Version 1.0
* ("License"); You may not use this file except in compliance with the License
* The Original Code is: vtiger CRM Open Source
* The Initial Developer of the Original Code is vtiger.
* Portions created by vtiger are Copyright (C) vtiger.
* All Rights Reserved.

- 29 -
*************************************************************************************/
/** David VALMINOS 12/11/2009
* Allows a webservice client to retrieve PDF data from a Vtiger's module (Invoice, Quotes, ...)
********************************************************/
function vtws_getpdfdata($id, $user){
global $log,$adb;
$log->debug("Entering function vtws_getpdfdata");
$webserviceObject = VtigerWebserviceObject::fromId($adb,$id);
$handlerPath = $webserviceObject->getHandlerPath();
$handlerClass = $webserviceObject->getHandlerClass();
require_once $handlerPath;
$handler = new $handlerClass($webserviceObject,$user,$adb,$log);
$meta = $handler->getMeta();
$entityName = $meta->getObjectEntityName($id);
$types = vtws_listtypes($user);
if(!in_array($entityName,$types['types'])){
throw new WebServiceException(WebServiceErrorCode::$ACCESSDENIED,"Permission to perform the
operation is denied");
}
if($meta->hasReadAccess()!==true){
throw new WebServiceException(WebServiceErrorCode::$ACCESSDENIED,"Permission to write is
denied");
}
if($entityName !== $webserviceObject->getEntityName()){
throw new WebServiceException(WebServiceErrorCode::$INVALIDID,"Id specified is incorrect");
}
if(!$meta->hasPermission(EntityMeta::$RETRIEVE,$id)){
throw new WebServiceException(WebServiceErrorCode::$ACCESSDENIED,"Permission to read given
object is denied");
}
$idComponents = vtws_getIdComponents($id);
if(!$meta->exists($idComponents[1])){
throw new WebServiceException(WebServiceErrorCode::$RECORDNOTFOUND,"Record you are trying
to access is not found");
}
$objectName = $webserviceObject->getEntityName();
$ids = vtws_getIdComponents($id);
$document_id = $ids[1];
$entity = get_module_pdf($objectName, $document_id);
VTWS_PreserveGlobal::flush();
$log->debug("Leaving function vtws_getpdfdata");
return $entity;
}
function get_module_pdf($modulename, $recordid) {
global $adb, $log;
$log->debug("Entering function get_module_pdf($recordid)");
$_pdf_data = GetRawPDFData($modulename, $recordid);
$recordpdf[0]["recordid"] = $recordid;
$recordpdf[0]["modulename"] = $modulename;

- 30 -
$recordpdf[0]["pdf_data"] = base64_encode($_pdf_data) ;
$log->debug("Leaving function get_module_pdf($recordid)");
return $recordpdf;
}
function GetRawPDFData($modulename, $recordid){
global $log, $currentModule;
$log->debug("Entering function GetRawPDFData. Module = $modulename record = $recordid");
$_REQUEST['record'] = $recordid;
$_REQUEST['module'] = $modulename;
$currentModule = $modulename;
$PDFBuffer = "";
$purpose = "webservice";
require("modules/".$modulename."/CreatePDF.php");
$log->debug("Leaving function GetRawPDFData. Module = $modulename record = $recordid");
return $PDFBuffer;
}
?>

• Hay que realizar las siguientes modificaciones:


Index: include/InventoryPDFController.php
===================================================================
--- include/InventoryPDFController.php (revisión: 3711)
+++ include/InventoryPDFController.php (copia de trabajo)
@@ -83,7 +83,7 @@
$pdfgenerator->setFooterViewer($this->getFooterViewer());
$pdfgenerator->setContentViewer($this->getContentViewer());

- $pdfgenerator->generate($filename, $type);
+ return $pdfgenerator->generate($filename, $type);
}

Index: vtlib/Vtiger/PDF/PDFGenerator.php
===================================================================
--- vtlib/Vtiger/PDF/PDFGenerator.php (revisión: 3711)
+++ vtlib/Vtiger/PDF/PDFGenerator.php (copia de trabajo)
@@ -168,7 +168,7 @@

function generate($name, $outputMode='D') {


$this->contentViewer->display($this);
- $this->pdf->Output($name, $outputMode);
+ return $this->pdf->Output($name, $outputMode);
}
}

Index: modules/Invoice/CreatePDF.php
===================================================================
--- modules/Invoice/CreatePDF.php (revisión: 3711)
+++ modules/Invoice/CreatePDF.php (copia de trabajo)
@@ -18,6 +18,9 @@
$id = vtlib_purify($_REQUEST['record']);
$filepath='test/product/'.$id.'_Invoice.pdf';
$controller->Output($filepath,'F'); //added file name to make it work in IE, also
forces the download giving the user the option to save
+} elseif($purpose == 'webservice') {
+ $log->debug("Switched to buffer. Purpose = ". $purpose);
+ $PDFBuffer = $controller->Output('','S'); // S means send the pdf output in buffer
instead of file
} else {

- 31 -
$controller->Output('Invoice.pdf', 'D');//added file name to make it work in IE, also
forces the download giving the user the option to save
exit();

Paso 3: Invocar la nueva operación dentro de nuestra aplicación cliente


<?php
require 'dologin.php';

//fill in the details of the invoice id. Can be obtained using vtwsbrowser
// select subject,id from invoice
// 16x90 is an existing invoice in the demo data of vtiger CRM
$invoiceId='16x90';
//sessionId is obtained from loginResult.
$params = array("sessionName"=>$sessionId, "operation"=>'getpdfdata', "id"=>$invoiceId);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) GetPDFData",$response);

//decode the json encode response from the server.


$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response GetPDFData",$jsonResponse);

//operation was successful get the token from the reponse.


if($jsonResponse['success']==false)
//handle the failure case.
die('GetPDFData failed: '.$jsonResponse['error']['message']);

// fix for IE catching or PHP bug issue


header("Pragma: public");
header("Expires: 0"); // set expiration time
header("Cache-Control: must-revalidate, post-check=0, pre-check=0");
// browser must download file from server instead of cache

// force download dialog


header("Content-Type: application/force-download");
header('Content-Type: application/pdf');
header("Content-Type: application/download");

// use the Content-Disposition header to supply a recommended filename and


// force the browser to display the save dialog.
header('Content-Disposition: attachment; filename="invoice.pdf"');

/*
The Content-transfer-encoding header should be binary, since the file will be read
directly from the disk and the raw bytes passed to the downloading computer.
The Content-length header is useful to set for downloads. The browser will be able to
show a progress meter as a file downloads. The content-lenght can be determines by
filesize function returns the size of a file.
*/
header("Content-Transfer-Encoding: binary");

echo base64_decode($jsonResponse['result']['0']['pdf_data']);
exit;
?>

- 32 -
Totales de Facturación

A modo de otro ejemplo haremos una operación que nos devolverá la suma
total de facturación de una cuenta.

--
-- Increment operation sequence
--
update vtiger_ws_operation_seq set id=id+1;

--
-- Insert webservice entry in operation table
--
INSERT INTO `vtiger_ws_operation` (
`operationid`,
`name` ,
`handler_path` ,
`handler_method` ,
`type` ,
`prelogin`
)
VALUES (
(select max(id) from vtiger_ws_operation_seq),'invoicetotals',
'include/Webservices/InvoiceTotals.php', 'vtws_invoicetotals', 'POST', '0'
);

--
-- Insert one entry for each service's parameter
--
INSERT INTO `vtiger_ws_operation_parameters` (
`operationid` ,
`name` ,
`type` ,
`sequence`
)
VALUES (
(select max(id) from vtiger_ws_operation_seq), 'id', 'string', '0'
);

Esta operación solo requiere el programa de operación (InvoiceTotals.php) que


se ve a continuación, no es necesario más cambios en vtiger CRM.

<?php
/************************************************************************************
* The contents of this file are subject to the vtiger CRM Public License Version 1.0
* ("License"); You may not use this file except in compliance with the License
* The Original Code is: JPL TSolucio, S.L. Open Source
* The Initial Developer of the Original Code is JPL TSolucio, S.L.
* Portions created by vtiger are Copyright (C) vtiger.
* All Rights Reserved.
*************************************************************************************/

- 33 -
function vtws_invoicetotals($id, $user){
global $log,$adb;
$log->debug("Entering function vtws_invoicetotals");
$webserviceObject = VtigerWebserviceObject::fromId($adb,$id);
$handlerPath = $webserviceObject->getHandlerPath();
$handlerClass = $webserviceObject->getHandlerClass();
require_once $handlerPath;
$handler = new $handlerClass($webserviceObject,$user,$adb,$log);
$meta = $handler->getMeta();
$entityName = $meta->getObjectEntityName($id);
$types = vtws_listtypes($user);
if($entityName == 'Accounts' and !in_array($entityName,$types['types'])){ // an
accountid has been given we need permission to accounts
throw new WebServiceException(WebServiceErrorCode::
$ACCESSDENIED,"Permission to perform the operation is denied on $entityName");
}
if(!in_array('Invoice',$types['types'])){ // we need access to invoices also
throw new WebServiceException(WebServiceErrorCode::
$ACCESSDENIED,"Permission to perform the operation is denied on Invoice");
}
if($meta->hasReadAccess()!==true){
throw new WebServiceException(WebServiceErrorCode::$ACCESSDENIED,"Permission to
write is denied");
}
if($entityName !== $webserviceObject->getEntityName()){
throw new WebServiceException(WebServiceErrorCode::$INVALIDID,"Id specified is
incorrect");
}
if(!$meta->hasPermission(EntityMeta::$RETRIEVE,$id)){
throw new WebServiceException(WebServiceErrorCode::$ACCESSDENIED,"Permission to
read given object is denied");
}
$idComponents = vtws_getIdComponents($id);
if(!$meta->exists($idComponents[1])){
throw new WebServiceException(WebServiceErrorCode::$RECORDNOTFOUND,"Record
you are trying to access is not found");
}
$ids = vtws_getIdComponents($id);
$accountid = $ids[1];
$itotrs=$adb->pquery('select sum(subtotal) as stot, sum(total) as ttot from
vtiger_invoice where accountid=?',array($accountid));
$totals=array('subtotal'=>$adb->query_result($itotrs,0,0),
'total'=>$adb->query_result($itotrs,0,1));
VTWS_PreserveGlobal::flush();
$log->debug("Leaving function vtws_invoicetotals");
return $totals;
}?>

- 34 -
Se puede llamar a esta operación desde un programa cliente como este:
<?php
require 'dologin.php';
//fill in the details of the account id. Can be obtained using vtwsbrowser
// select accountname,id from accounts
// 3x4 is an existing account in the demo data of vtiger CRM
$accountId='3x4';
//sessionId is obtained from loginResult.
$params = array("sessionName"=>$sessionId, "operation"=>'invoicetotals',
"id"=>$accountId);
//Create must be POST Request.
$httpc->post("$endpointUrl", $params, true);
$response = $httpc->currentResponse();
if ($dcall==1) printvar("Raw response (json) InvoiceTotals",$response);
//decode the json encode response from the server.
$jsonResponse = Zend_JSON::decode($response['body']);
if ($dcall==1) printvar("Webservice response InvoiceTotals",$jsonResponse);
//operation was successful get the token from the reponse.
if($jsonResponse['success']==false)
//handle the failure case.
die('InvoiceTotals failed: '.$jsonResponse['error']['message']);
printvar("Invoice Totals for Account",$jsonResponse);
?>

Crear ficheros de usuarios

Uno de los inconvenientes de crear usuarios desde REST es que no se generan


los ficheros auxiliares, por eso se puede crear una operación adicional que
regenere todos los ficheros, creando de paso los que faltan. De esta manera se
puede llamar a esta operación al finalizar la creación de un usuario.
Hilo del foro donde surgió esta idea
<?php
$Vtiger_Utils_Log = true;
include_once 'vtlib/Vtiger/Module.php';
Vtiger_Access::syncSharingAccess();
?>

- 35 -
Librerías de Cliente
Client Library. version 1.4
Los programadores de vtiger no solo han creado un interfaz webservice basado
en REST para poder integrar la aplicación de manera sencilla con otras
aplicaciones si no que además han creado una librería que proporciona un nivel
de abstracción superior haciendo que sea más sencillo utilizar este servicio.
Esta librería se llama vtwsclib (vtiger CRM Web Services Client Library) y es un
conjunto de programas que facilitan el uso de los servicios REST de vtiger CRM.
Utilizando estas librerías puedes escribir nuevas aplicaciones que integran con
vtiger CRM de manera sencilla.
La versión actual de la colección de vtwsclib proporciona programas para
trabajar con PHP, Javascript, Java y Python.

Instalación
Descomprimir el fichero vtwsclib-x.y.zip en una carpeta donde vayas a
desarrollar tu aplicación.

Requisitos
Es necesario tener instalado la extensión php_curl de PHP para utilizar la
versión PHP de la Librería de Cliente.

Librería Cliente PHP


El programa Cliente PHP (class Vtiger_WSClient) define las siguientes
funciones:
• doLogin
• doListTypes
• doDescribe
• doCreate
• doRetrieve
• doQuery
• doInvoke
• lastError
• toJSON
• toJSONString

- 36 -
Funcionalidades de la Clase
class Vtiger_WSClient se define en el fichero vtwsclib/Vtiger/WSClient.php.
Incluye esta clase en tu aplicación como se indica a continuación.
Perfil Vtiger_WSClient(url)
Parámetros url – cadena vtiger CRM URL
Valor Devuelto Objeto WSClient para acceder a la aplicación
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');
$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);
?>

doLogin
Perfil Boolean doLogin(nombreusuario, claveacceso)
Parámetros nombreusuario – cadena nombre usuario vtiger CRM
claveacceso – cadena clave univoca del usuario, accesible en las
Preferencias del usuario en vtiger CRM como se puede ver en la imagen a
continuación
Valor Devuelto Verdadero – si se consigue acceder correctamente a la aplicación
Falso – si no logra conectarse
Explicación Esta función inicializa la clase Vtiger_WSClient con un sessionId si consigue
conectarse que es imprescindible para ejecutar operaciones subsiguientes.
Ejemplo <?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 echo 'Login Successful';
?>

- 37 -
Clave de Acceso

doListTypes
Perfil array doListTypes()
Parámetros
Valor Devuelto array – con la lista de módulos disponibles al usuario conectado
Ejemplo <?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>”;
}
?>

doDescribe
Perfil array doDescribe(modulo)
Parámetros modulo – cadena nombre del módulo del que queremos obtener la
descripción
Valor Devuelto array – lista de campos accesibles y operaciones permitidas sobre el módulo
indicado por el usuario conectado
Explicación Obtiene información sobre los campos accesibles por el usuario conectado
así como a lista de operación que le son permitidas.
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');
$url = 'http://en.vtiger.com/wip';

- 38 -
$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];
}
?>

doCreate
Perfil array doCreate(modulo, mapa_valores)
Parámetros modulo – cadena nombre del módulo para el que queremos crear un registro
mapa_valores – array con los campos a insertar, el índice será el nombre del
campo y el contenido el valor del mismo
Valor Devuelto array – contiene todos los valores insertados, además del webservice id del
nuevo registro si se ha podido crear, si no se ha podido crear estará vacío
(falso)
Explicación Sirve para insertar nuevos registros en la aplicación.
Puede fallar si algún campo obligatorio no está presente.
El valor devuelto contendrá el identificador del registro insertado que estará
en el formato <moduleid>'x'<recordid>. Puedes utilizar el método
getRecordId para obtener solo el recordid
Ejemplo <?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']);
}
}
?>

doRetrieve
Perfil array doRetrieve(recordId)
Parámetros recordId – cadena con el formato <moduleid>'x'<recordid>
Valor Devuelto array – contiene todos los valores del registro indicado en el módulo
indicado si existe y el usuario tiene permiso para acceder a el, si no se ha
podido acceder estará vacío (falso)
Explicación Obtener información de los registros contenidos en la base de datos
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');

- 39 -
$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'];
}
?>

doQuery
Perfil array doQuery(query)
Parámetros query – cadena con la consulta webservice a ejecutar
Valor Devuelto array – contiene todos los registros encontrados con los valores de las
columnas pedidas, si no se ha podido encontrar ningún registro estará vacío
(falso)
Explicación Obtiene un conjunto de filas con información de los registros contenidos en
la base de datos
Puedes utilizar el método getResultColumns para obtener el nombre de las
columnas devueltas
Ejemplo <?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
}
}
}
?>

doInvoke
Perfil objeto doInvoke(metodo, parametros, tipo)
Parámetros metodo – cadena con el nombre del método a ejecutar
parametros – array con los valores necesarios para ejecutar el método
solicitado
tipo – cadena POST o GET, cómo se ha de pasar los parámetros
Valor Devuelto objeto – depende del método solicitado
Explicación Permite ejecutar cualquier método expuesto por el interface webservice.
Normalmente métodos personalizados REST.
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');

- 40 -
$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
}
}
?>

lastError
Perfil array lastError()
Parámetros
Valor Devuelto array – con el código y mensaje de error, falso si la última operación tuvo
éxito.
Explicación Permite obtener el estado del resultado de ejecución de la última operación
y una explicación el error producido en su caso
Ejemplo <?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'];
}
}
?>

toJSON
Perfil objeto toJSON(inputString)
Parámetros inputString – cadena en formato JSON
Valor Devuelto array/cadena – objeto PHP correspondiente a la cadena JSON dada.
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');
$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);
$phpmap = $client->toJSON( '{ "A" : "B" }' );
?>

- 41 -
toJSONString
Perfil string toJSONString(input)
Parámetros input – array/cadena
Valor Devuelto cadena – cadena en formato JSON
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo <?php
include_once('vtwsclib/Vtiger/WSClient.php');
$url = 'http://en.vtiger.com/wip';
$client = new Vtiger_WSClient($url);
$jsonstring = $client->toJSONString( { 'a'=>'ValueA'} );
?>

- 42 -
Librería Cliente Javascript

Es necesario incluir el siguiente código en el programa javascript para poder


acceder a los servicios REST de vtiger CRM:
<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>

El programa Cliente Javascript (Vtiger_WSClient) define las siguientes


funciones:
• doLogin
• doListTypes
• doDescribe
• doCreate
• doRetrieve
• doQuery
• doInvoke
• lastError
• toJSON
• toJSONString
La mayoría de operaciones de esta librería se ejecutan vía AJAX, de manera
asíncrona.

Funcionalidades de la Clase
class Vtiger_WSClient se define en el fichero vtwsclib/Vtiger/WSClient.js
Perfil Vtiger_WSClient(url)
Parámetros url – cadena vtiger CRM URL
Valor Devuelto Objeto WSClient para acceder a la aplicación
Ejemplo <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);
</script>

doLogin
Perfil doLogin(nombreusuario, claveacceso, callback)
Parámetros nombreusuario – cadena nombre usuario vtiger CRM
claveacceso – cadena clave univoca del usuario, accesible en las
Preferencias del usuario en vtiger CRM como se puede ver en la imagen a
continuación
callback – representa la función a llamar una vez conseguido la validación
como se explica más abajo.
Valor Devuelto Verdadero – si se consigue acceder correctamente a la aplicación

- 43 -
Falso – si no logra conectarse
Explicación Esta función inicializa la clase Vtiger_WSClient con un sessionId si consigue
conectarse que es imprescindible para ejecutar operaciones subsiguientes.
Una vez conectado se ejecutará la función callback.
Ejemplo <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>

Clave de Acceso

Argumento Callback
La mayoría de operaciones de esta librería se ejecutan vía AJAX, de manera
asíncrona. Por ello, es necesario definir una función de retorno de esta llamada
que será ejecutad cuando responda el servidor.
El argumento callback puede ser:
• Función de Referencia
• Mapa de retorno con el formato:
{
'function' : <Function Reference>,
'arguments' : {'arg1' : 'value1', 'arg2' : ['value2']}
}

Si tenemos una función de referencia, será ejecutada con el primer parámetro


siendo el resultado de la llamada.

- 44 -
Si tenemos un mapa, se ejecutará la función indicada con el resultado de la
llamada como primer argumento y los subsiguientes indicados en la definición.

doListTypes
Perfil array doListTypes(callback)
Parámetros callback
Valor Devuelto array – con la lista de módulos disponibles al usuario conectado
Ejemplo <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>

doDescribe
Perfil array doDescribe(modulo,callback)
Parámetros modulo – cadena nombre del módulo del que queremos obtener la
descripción
callback
Valor Devuelto array – lista de campos accesibles y operaciones permitidas sobre el módulo
indicado por el usuario conectado
Explicación Obtiene información sobre los campos accesibles por el usuario conectado
así como a lista de operación que le son permitidas.
Ejemplo <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)

- 45 -
alert('Module = ' + module + ', Details = ' +
client.toJSONString(result));
}
</script>

doCreate
Perfil array doCreate(modulo, mapa_valores,callback)
Parámetros modulo – cadena nombre del módulo para el que queremos crear un registro
mapa_valores – array con los campos a insertar, el índice será el nombre del
campo y el contenido el valor del mismo
callback
Valor Devuelto array – contiene todos los valores insertados, además del webservice id del
nuevo registro si se ha podido crear, si no se ha podido crear estará vacío
(falso)
Explicación Sirve para insertar nuevos registros en la aplicación.
Puede fallar si algún campo obligatorio no está presente.
El valor devuelto contendrá el identificador del registro insertado que estará
en el formato <moduleid>'x'<recordid> . Puedes utilizar el método
getRecordId para obtener solo el recordid
Ejemplo <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>

doRetrieve
Perfil array doRetrieve(recordId,callback)
Parámetros recordId – cadena con el formato <moduleid>'x'<recordid>
callback
Valor Devuelto array – contiene todos los valores del registro indicado en el módulo
indicado si existe y el usuario tiene permiso para acceder a el, si no se ha
podido acceder estará vacío (falso)
Explicación Obtener información de los registros contenidos en la base de datos
Ejemplo <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

- 46 -
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>

doQuery
Perfil array doQuery(query,callback)
Parámetros query – cadena con la consulta webservice a ejecutar
callback
Valor Devuelto array – contiene todos los registros encontrados con los valores de las
columnas pedidas, si no se ha podido encontrar ningún registro estará vacío
(falso)
Explicación Obtiene un conjunto de filas con información de los registros contenidos en
la base de datos
Puedes utilizar el método getResultColumns para obtener el nombre de las
columnas devueltas
Ejemplo <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>

doInvoke
Perfil objeto doInvoke(callback,metodo, parametros, tipo)
Parámetros callback
metodo – cadena con el nombre del método a ejecutar
parametros – array con los valores necesarios para ejecutar el método
solicitado

- 47 -
tipo – cadena POST o GET, cómo se ha de pasar los parámetros
Valor Devuelto objeto – depende del método solicitado
Explicación Permite ejecutar cualquier método expuesto por el interface webservice.
Normalmente métodos personalizados REST.
Ejemplo <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>

lastError
Perfil array lastError()
Parámetros
Valor Devuelto array – con el código y mensaje de error, falso si la última operación tuvo
éxito.
Explicación Permite obtener el estado del resultado de ejecución de la última operación
y una explicación el error producido en su caso
Ejemplo <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>

- 48 -
toJSON
Perfil objeto toJSON(inputString)
Parámetros inputString – cadena en formato JSON
Valor Devuelto array/cadena – objeto PHP correspondiente a la cadena JSON dada.
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);
var jsobj = client.toJSON( '{ “A” : “B” }' );
</script>

toJSONString
Perfil string toJSONString(input)
Parámetros input – array/cadena
Valor Devuelto cadena – cadena en formato JSON
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo <script type='text/javascript'>
var url = 'http://en.vtiger.com/wip';
var client = new Vtiger_WSClient(url);
var jsonstring = client.toJSONString( { 'a'=>'ValueA'} );
</script>

Librería Cliente Java


El programa Cliente Java (com.vtiger.vtwsclib.WSClient) define las siguientes
funciones:
• doLogin
• doListTypes
• doDescribe
• doCreate
• doRetrieve
• doQuery
• doInvoke
• lastError
• toJSON
• toJSONString
y tiene las siguientes dependencias:
• es necesario tener vtwsclib/java y vtwsclib/java/deps en la variable
CLASSPATH cuando se ejecuta desde la línea de comando. El camino definido
en el fichero MANIFEST busca las dependencias en el mismo directorio en el

- 49 -
que se encuentra el programa vtwsclib.jar, así que si se producen
excepciones del tipo java.lang.NoClassDefFoundError asegurate de tener
correctamente definida la variable CLASSPATH.
• vtwsclib.jar depende de la librería HTTP Components que se incluye en
vtwsclib/java/deps (Apache License 2.0)
• vtwsclib.jar viene incorporado con la librería json-simple que puede ser
reutilizada dentro de la aplicación final para la manipulación de JSON (Apache
License 2.0)

Funcionalidades de la Clase
class com.vtiger.vtwsclib.WSClient se define en el fichero java/vtwsclib.jar.
Incluye esta clase en tu aplicación como se indica a continuación.
Perfil Vtiger_WSClient(url)
Parámetros url – cadena vtiger CRM URL
Valor Devuelto Objeto WSClient para acceder a la aplicación
Ejemplo import com.vtiger.vtwsclib.WSClient;
/* Create Vtiger Webservice client */
WSClient client = new WSClient(“http://en.vtiger.com/wip”);

doLogin
Perfil Boolean doLogin(nombreusuario, claveacceso)
Parámetros nombreusuario – cadena nombre usuario vtiger CRM
claveacceso – cadena clave univoca del usuario, accesible en las
Preferencias del usuario en vtiger CRM como se puede ver en la imagen a
continuación
Valor Devuelto Verdadero – si se consigue acceder correctamente a la aplicación
Falso – si no logra conectarse
Explicación Esta función inicializa la clase Vtiger_WSClient con un sessionId si consigue
conectarse que es imprescindible para ejecutar operaciones subsiguientes.
Ejemplo 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");
}

- 50 -
Clave de Acceso

doListTypes
Perfil java.util.Map doListTypes()
Parámetros
Valor Devuelto java.util.Map – con la lista de módulos disponibles al usuario conectado
Ejemplo 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"));
}
}

doDescribe
Perfil org.json.simple.JSONObject doDescribe(modulo)
Parámetros modulo – cadena nombre del módulo del que queremos obtener la
descripción
Valor Devuelto org.json.simple.JSONObject – lista de campos accesibles y operaciones
permitidas sobre el módulo indicado por el usuario conectado

- 51 -
Explicación Obtiene información sobre los campos accesibles por el usuario conectado
así como a lista de operación que le son permitidas.
Ejemplo 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);
}
}

doCreate
Perfil org.json.simple.JSONObject doCreate(modulo, mapa_valores)
Parámetros modulo – cadena nombre del módulo para el que queremos crear un registro
mapa_valores – java.util.Map con los campos a insertar, el índice será el
nombre del campo y el contenido el valor del mismo
Valor Devuelto org.json.simple.JSONObject – contiene todos los valores insertados, además
del webservice id del nuevo registro si se ha podido crear, si no se ha podido
crear estará vacío (falso)
Explicación Sirve para insertar nuevos registros en la aplicación.
Puede fallar si algún campo obligatorio no está presente.
El valor devuelto contendrá el identificador del registro insertado que estará
en el formato <moduleid>'x'<recordid>. Puedes utilizar el método
getRecordId para obtener solo el recordid
Ejemplo 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);
}
}

- 52 -
doRetrieve
Perfil org.json.simple.JSONObject doRetrieve(recordId)
Parámetros recordId – cadena con el formato <moduleid>'x'<recordid>
Valor Devuelto org.json.simple.JSONObject – contiene todos los valores del registro indicado
en el módulo indicado si existe y el usuario tiene permiso para acceder a el,
si no se ha podido acceder estará vacío (falso)
Explicación Obtener información de los registros contenidos en la base de datos
Ejemplo 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);
}
}

doQuery
Perfil org.json.simple.JSONArray doQuery(query)
Parámetros query – cadena con la consulta webservice a ejecutar
Valor Devuelto org.json.simple.JSONArray – contiene todos los registros encontrados con los
valores de las columnas pedidas, si no se ha podido encontrar ningún
registro estará vacío (falso)
Explicación Obtiene un conjunto de filas con información de los registros contenidos en
la base de datos
Puedes utilizar el método getResultColumns para obtener el nombre de las
columnas devueltas
Ejemplo 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()) {

- 53 -
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);
}}}}

doInvoke
Perfil objeto doInvoke(metodo, parametros, tipo)
objeto doInvoke(metodo, parametros) - tipo es GET
Parámetros metodo – cadena con el nombre del método a ejecutar
parametros – array con los valores necesarios para ejecutar el método
solicitado
tipo – cadena POST o GET, cómo se ha de pasar los parámetros
Valor Devuelto objeto – depende del método solicitado
Explicación Permite ejecutar cualquier método expuesto por el interface webservice.
Normalmente métodos personalizados REST.
Ejemplo 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);
}
}

lastError
Perfil objeto lastError()
Parámetros
Valor Devuelto objeto – con el código y mensaje de error, falso si la última operación tuvo
éxito.
Explicación Permite obtener el estado del resultado de ejecución de la última operación
y una explicación el error producido en su caso
Ejemplo 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”);

- 54 -
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);
}
}
}

toJSON
Perfil objeto toJSON(inputString)
Parámetros inputString – cadena en formato JSON
Valor Devuelto org.json.simple.JSONArray o org.json.simple.JSONObject – objeto
correspondiente a la cadena JSON dada.
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo import com.vtiger.vtwsclib.WSClient;
/* Create Vtiger Webservice client */
WSClient client = new WSClient(“http://en.vtiger.com/wip”);
Object jsonObj = client.toJSON( “{ \“A\” : \“B\” }”);

toJSONString
Perfil string toJSONString(input)
Parámetros input – Java JSON Array o Map o String
Valor Devuelto cadena – cadena en formato JSON
Explicación Método auxiliar para manipular objetos y transformarlos para su uso en
distintos escenarios habituales de REST
Ejemplo 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);

- 55 -
Programa vtiger CRM Webservices
Browser (vtwsbrowser)
vtwsbrowser
vtwsbrowser es un programa concebido como una herramienta de desarrollo,
que ofrece la capacidad de ejecutar consultas del servicio web e inspeccionar
el resultado.
Está desarrollado en PHP utilizando la Librería de Cliente PHP y hereda sus
requerimientos así como también necesita la extensión php_curl.
La instalación es tan sencilla como descomprimir el programa en una carpeta
accesible desde un servidor web con capacidad de ejecutar PHP y apuntar el
navegador a este directorio.
El programa es capaz de conectarse a cualquier instalación de vtiger CRM al
que tenemos acceso. La primera pantalla nos pide los datos de acceso al CRM.

vtwsbrowser login
Una vez conectados el programa nos permite ejecutar cualquier consulta
soportada por el webservice y ver los resultados de la misma.

- 56 -
vtwsbrowser query
JPL TSolucio, S.L. ha creado además una extensión a este programa que
mostrará todos los módulos y campos a los que tenemos acceso.

- 57 -
Procedimiento de acceso a
usuarios
• Crear el nuevo usuario normalmente en la aplicación
• Asignar el rol y perfiles correspondientes, así como las características de
usuario especial si procede
• A partir de este momento el usuario ya puede acceder tanto a la aplicación
como al servicio REST
• Hacer llegar al usuario los siguientes datos:
• URL de la aplicación
• nombre de usuario
• contraseña para acceder a la aplicación
• clave de acceso para acceder al servicio REST
• leer este manual

Acceso al código de este libro


Para consultar y descargar el código de este libro, puede hacerse desde el
repositorio SVN siguiente:
http://crmevolutivo.com/svn/vtigerCRM/webservice/

Si tenéis cualquier duda o pregunta, por favor mandadnos un email a


info@tsolucio.com y con mucho gusto os daremos toda la ayuda posible.

Gracias y hasta pronto.


TSOLUCIO

- 58 -

También podría gustarte