Manual de Desarrollo Web Services Vtiger "Español"

 

 

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, 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 vtiger CRM y no asume ninguna responsabili responsabilidad dad 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.................................................... Introducción................ ........................................................................ .....................................................2 .................2 Formato de Llamada......................................................... Llamada...................................................................... ......................... ..............2 ..2 Formato de Respuesta............................................................................... Respuesta.................................................................................2 ..2 Operaciones.................................................................................................3 Nombre de Sesión....................... Sesión............................................................ .................................................................4 ............................4 Seguridad.....................................................................................................4  Tipos de Datos utilizados.......................... utilizados................................................................ ................................................... .............4 4 VtigerObject.............................................................................................4 Id Format........... Format............................................... .......................................................................................4 ...................................................4 Map..........................................................................................................4  TimeStamp.....................................................  TimeStamp................ ............................................................................ ..........................................4 ...4 GetChallengeResult..................................................................................5 LoginResult................................................. LoginResult............. ........................................................................ ..............................................5 ..........5 SyncResult................................................ SyncResult............ ......................................................................... ................................................5 ...........5 Operaciones.....................................................................................................6 Get Challenge..............................................................................................6 Login............................................................................................................6 Create..........................................................................................................6 Retrieve...................................................... Retrieve................. ......................................................................... ..................................................7 ..............7 Update.........................................................................................................7 Delete..........................................................................................................7 Query...........................................................................................................7 Sync.............................................................................................................8 Logout..........................................................................................................9 List Types........................ Types............................................................ .............................................................................9 .........................................9 Describe.......................................................................................................9 Extend Session...................... Session.......................................................... .....................................................................11 .................................11 Entidades CRM........................ CRM............................................................ .......................................................................11 ...................................11  Tipos de campos...................................... campos.......................................................................... ................................................. ..................12 .....12 picklist........................................................................................................12 multipicklist................................................................................................12 reference........................................................ reference................... ......................................................................... ............................................12 ........12 datetime....................................................... datetime................... ........................................................................ ..............................................12 ..........12 date........................................................... date....................... ........................................................................ .................................................12 .............12 time........................................................... time....................... ........................................................................ .................................................13 .............13 string..........................................................................................................13 text......................................................... text..................... ........................................................................ ....................................................13 ................13 password....................................................................................................13 boolean......................................................................................................13 integer........................................................ integer.................... ........................................................................ ................................................13 ............13 double........................................................................................................13 decimal......................................................................................................13 owner.........................................................................................................13 autogenerated...........................................................................................13 email..........................................................................................................13 phone.........................................................................................................14 skype...................................................... skype.................. ........................................................................ ....................................................14 ................14

 

url................................................................................................ url........................................................... ....................................................14 ...............14 file..............................................................................................................14 Problemas conocidos....................................................... conocidos........................................................................ .............................. .............14 14  Tutorial vtiger CRM Webservices......................... Webservices.......................................................................16 ..............................................16 Requerimientos......................................... Requerimientos..... ........................................................................ .....................................................16 .................16 Accediendo al Sistema...................... Sistema.......................................................... .............................................................16 .........................16 Get Challenge............................................................................................17 Login..........................................................................................................18 Obteniendo Información de los Objetos.........................................................19 List Types........................ Types............................................................ ...........................................................................19 .......................................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............................................................................. Consulta...............................................................................23 ..23 Operación de Sincronización.................... Sincronización......................................................... ......................................................26 .................26 Desconexión del Servicio........................... Servicio............................................................... ............................................... ................27 .....27 Utilizar sesión de aplicación para acceder a webservice...............................27 webservice............................... 27 Definir nuevas operaciones.............................................................................. operaciones...............................................................................28 .28 GetPDFdata........................................ GetPDFdata.... ......................................................................... ............................................................28 .......................28  Totales de Facturación............................. Facturación.................................................................. ......................................................33 .................33 Crear ficheros de usuarios........................................................................ usuarios.............................................................................35 .....35 Librerías de Cliente............................ Cliente................................................................ ................................................................36 ............................36 Instalación..................................................................................................36 Requisitos............................................... Requisitos........... ........................................................................ ....................................................36 ................36 Librería Cliente PHP.......................................................................................36 Funcionalidades de la Clase................................................................... Clase.......................................................................37 ....37 doLogin......................................................................................................37 doListTypes................................................................................................38 doDescribe.................................................................................................38 doCreate....................................................................................................39 doRetrieve.................................................... doRetrieve................ ........................................................................ ..............................................39 ..........39 doQuery.....................................................................................................40 doInvoke....................................................................................................40 lastError.....................................................................................................41 toJSON........................................................................................................41 toJSONString..............................................................................................42 Librería Cliente Javascript............................................................................. Javascript..............................................................................43 .43 Funcionalidades de la Clase................................................................... Clase.......................................................................43 ....43 doLogin......................................................................................................43 Argumento Callback.............................................................................. Callback...............................................................................44 .44 doListTypes................................................................................................45 doDescribe.................................................................................................45 doCreate....................................................................................................46 doRetrieve.................................................... doRetrieve................ ........................................................................ ..............................................46 ..........46 doQuery.....................................................................................................47 doInvoke....................................................................................................47 lastError.....................................................................................................48

 

toJSON........................................................................................................49 toJSONString..............................................................................................49 Librería Cliente Java............................ Java................................................................ ...........................................................49 .......................49 Funcionalidades de la Clase................................................................... Clase.......................................................................50 ....50 doLogin......................................................................................................50 doListTypes................................................................................................51 doDescribe.................................................................................................51 doCreate....................................................................................................52 doRetrieve.................................................... doRetrieve................ ........................................................................ ..............................................53 ..........53 doQuery.....................................................................................................53 doInvoke....................................................................................................54 lastError.....................................................................................................54 toJSON........................................................................................................55 toJSONString..............................................................................................55 Programa vtiger CRM Webservices Browser Browser (vtwsbrowser)......................... (vtwsbrowser)..............................56 .....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 REST   define un sistema consistente y seguro para acceder a la El protocolo REST 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 imp implem lement entaci ación ón del pr proto otocol colo o rea realiz lizada ada por vti vtiger ger CR CRM M utiliz utiliza a el formato  formato   JSON para  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 identificación que  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,, así que toda la comunicación REST - API está basado en el protocolo REST entre cliente y servidor ocurre sobre HTTP como peticiones GET o POST. JSON para  para codificar las peticiones y las respuestas  JSON - se utiliza el formato JSON Peticiones y Respuestas - La aplicación cliente prepara y envía peticiones de serv se rvic icio io al AP API, I, el AP APII proc proces esa a la pe peti tici ción ón y de devu vuel elve ve un una a re resp spue uest sta, a, 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: pe perrmite ite utili tiliza zarr la ses esió ión n def efin inid ida a al va vali lida darrse en la aplica apli caci ción ón,, de es esta ta ma mane nera ra se pu pued ede e ac acce cede derr al se serv rvic icio io de ma mane nera ra 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  ('x'). Existe un campo especial, llamado Id, que posee el formato de un identificador  identificador  de entidad  entidad  ('x'), que es la clave de identificación de únic ún ica a de dell ob obje jeto to.. Este Este ca camp mpo o es está tá pres presen ente te para para cu cual alqu quie ierr ob obje jeto to que 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úm número ero enter entero o lar largo go rep repres resent entand ando o el núm número ero de seg segund undos os des desde de Unix Unix   Epoch.. 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: Perfil: Tipo envío:

Obtiene una clave de desafío para poder realizar el acceso al servicio getchallenge(username:String):GetChallengeResult GET (obligatorio, no puede ser POST)

username: nombre de usuario dado de alta y activo en vtiger CRM Parámetros: Respuesta: Un objeto GetChallengeResult con 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 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 Un objeto LoginResult con LoginResult con el identificador de la sesión, la versión del API y el Respuesta: identificador del usuario Formato URL: http://vtiger_url/webservice.php? operation=login&username=[username]&accessKey operation=login&usernam e=[username]&accessKey=[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: Perfil: Tipo envío: Parámetros:

Crear un nuevo registro en la aplicación create(element:Map, create(element:Ma p, elementType:String): VtigerObject POST (obligatorio, no puede ser GET) 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 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 id]&element=[object]&elem entType=[object type]

-6-

 

Retrieve Propósito: Perfil: Tipo envío: Parámetros: Respuesta: Formato URL:

Obtener todos los valores de un registro en la aplicación retrieve(id: Id): VtigerObject GET (obligatorio, no puede ser POST) id: El identificador del registro en el formato de identificador Un objeto VtigerObject con VtigerObject con todos los datos del registro encontrado http://vtiger_url/webservice.php?operation=retrieve&session_name=[session id]&id=[object id]

Update Propósito: Perfil: Tipo envío: Parámetros: Respuesta:

Actualizar TODOS los campos de un registro en la aplicación update(object: VtigerObject): VtigerObject POST (obligatorio, no puede ser GET) object: El  El VtigerObject  VtigerObject a actualizar Un objeto VtigerObject con 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: Perfil: Tipo envío: Parámetros: Respuesta: Formato URL:

Eliminar un registro de la aplicación delete(id:Id):Map POST (obligatorio, no puede ser GET) id: El identificador del identificador del objeto a eliminar Un objeto Map con Map con un solo valor 'successfull' 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 query(queryString : String): [VtigerObject] Perfil: GET (obligatorio, no puede ser POST) Tipo envío: Parámetros: queryString: La consulta a procesar Respuesta: Un objeto Map con 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 * | | from [where ] [order by ] [limit [, ]]; •

•

•

•

•

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 condition condit ionals als:: ope operac racion iones es de con condic dición ión o clá cláusu usulas las “en “en” ” (in (in)) o cla claus usula ulas s “como” (like) separadas por operadores 'and' o 'or'. Estas condiciones se procesan de izquierda a derecha. conditional operators: , =, =, !=

•

in clauses: in ()

•

value list: lista de valores separados por comas

•

like clauses: like 'sqlregex'

•

•

el parámetro en la cláusula order by está limitado a dos columnas m, n: va valo lore res s en ente tero ros s qu que e es espe peci cifi fica can n el de desp spla laza zami mien ento to y el lími límite te de registros devueltos

Sync 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 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 SyncResult con los cambios Formato URL: http://vtiger_url/webservice.php?operation=sync&sessionName=[session id]&modifiedTime=[timestamp]&elementType=[elementType]

Propósito:

-8-

 

Logout Propósito: Perfil: Tipo envío: Parámetros: Respuesta: Formato URL:

Desconectar del servicio, elimina la sesión y la invalida para el uso logout(): Map GET (obligatorio, no puede ser POST) Un objeto Map con Map con un único valor 'successfull' http://vtiger_url/webservice.php?operation=logout&sess http://vtiger_url/webservice.ph p?operation=logout&sessionName=[session ionName=[session id]

List Types Propósito: Perfil: Tipo envío: Parámetros: Respuesta:

Lista el nombre de todos los objetos vtiger crm disponibles en el servicio listtypes(): Map GET (obligatorio, no puede ser POST)

Un objeto Map con 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: Perfil: Tipo envío: Parámetros: Respuesta: Formato URL:

Devuelve el conjunto sobre el objeto pedidode operaciones permitidas por el usuario conectado describe(elementType:: String): DescribeResult describe(elementType GET (obligatorio, no puede ser POST) elementType: el nombre del módulo del que se quiere la descripción Un objeto DescribeResult (ver a continuación) con la información del módulo 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  - va valo lorr bo bool olea eano no indi indica cand ndo o si el us usua uari rio o co cone nect ctad ado o pu pued ede e actualizar registros. 5. deleteable  - va valo lorr bo bool olea eano no indi indica cand ndo o si el us usua uari rio o co cone nect ctad ado o pu pued ede e eliminar registros. 6. retrieveable  - val valor or boo boolea leano no indica indicando ndo si el usuari usuario o con conect ectado ado pue puede de 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  - va valo lorr bo bool olea eano no qu que e indi indica ca si el camp campo o es obli obliga gato tori rio, o, los 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 campo contiene,, al meno menos, s, un elemen elemento to denomin denominado ado 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  - un una a ca cade dena na co con n el fo form rmat ato o hh hh:m :mm, m, el fo form rmat ato o se ba basa sa en las 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   -por Es Esto tos s so son nCRM, los los estos ca camp mpos os cuyo cuyos s valo va lore res s so son n ge gene nera rado dos s automáticamente vtiger 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 cont co nten endr drá á do dos s elem elemen ento tos, s,  picklistValues  que es una una lis lista de valo alores 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 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 Eventos PreCo reCont nta act cto os

El módulo de calendario gestion iona los eventos, reunion iones y tareas. El módulo de Eventos gestiona eventos y reuniones, no tareas. El módu módulo lo de P Pre reCo Cont ntac acto tos s sir sirve ve para para ges gestio tiona narr inf info orma rmación ión de de potenciales clientes. Cuentas El módulo de Cuentas representa las empresas con las que trabajas. Contactos El mó módulo de de Co Contactos re representa pe personas co con lla as qu que tr trabajamos, posiblemente dentro de las empresas. Opor Op ortu tuni nida dade des s El mód módul ulo o de Opo Oport rtun unid idad ades es ges gesti tion onas as las las op opor ortu tuni nida dade des s de neg negoc ocio io que que tenemos con nuestros clientes. Productos El mó módulo de de Pr Productos ge gestiona lo los bi bienes qu que ve vende nu nuestra em empresa. Documentos El mó módulo de de Do Documentos ge gestiona la la ba base de de d do ocumentos tos y notas Carpetas Docum Documento ento Las carpetas de Documentos no nos s permiten agrupar documentos. documentos. Emails El módulo de Emails registra los emails enviados y recibidos clientes. Incidencias El mó módulo de de IIn ncide idencias re registra lo los p prroblemas y/ y/o pr preguntas qu que no nos hacen los clientes sobre nuestros servicios. Faq El módulo de FAQ gestionar la base de conocimiento de la empresa. Proveedores El mó módulo de de Pr Proveedores si sirve pa para ge gestionar lo los p prroveedores  Tarifas Las tarifas gestionan gestionan los precios de nuestros productos. productos. Pr Pres esup upue uest stos os El módu módulo lo de Pr Pres esup upue uest stos os gest gestio iona na las las ofer oferta tas s qu que e hac hacem emos os a clien liente tes. s. Or Orde den n Com Compr pra a El módu módulo lo de Or Orde dene nes s de Comp Compra ra re regi gist stra ra las las comp compra ras s que que ha hace cemo mos s Ord rde en Ve Venta El mó módulo de de Or Ordenes de de Ve Venta re registra lo los pe pedidos re recibidos Factura El módulo de Facturas gestiona las facturas que emitimos. Campañas El mó módulo de de Ca Campañas re registra llo os eventos de Ma Marketing. Usuarios El módulo de 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

picklistV pickli stValu alues es Una llist ista a de po posib sibles les v valo alores res.. defaul def aultV tValu alue e Esp Especi ecific fica a qué qué va valor lor es el val valor or p por or d defe efecto cto de lla a lis lista. ta. 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á contendrá además, s, otro elemento llamad llamado o refersTo  que es una matriz que contiene el nombre de los módulos con los que puede relacionarse.

Nombre refersTo name

Descripción Una lista de nombres de m mó ódulos con los que se puede relacionar este campo. 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:  Un Una a ca cade dena na qu que e repr repres esen enta ta un una a fe fech cha, a, el arra array y co cont nten endr drá, á, además, otro element además, elemento o llama llamado do format  que   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 format name

Descripción formato en el que se espera que esté el valor de este campo. Nombre del campo

- 12 -

 

time Descripción:  Una caden cadena a en form formato ato hh:mm. Se basa en el form formato ato 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 maxUploadFileSiz maxUploadF ileSize e name

Descripción Tamañ Tamaño om máximo áximo perm permitido itido para el fficher ichero o qu que es se em manda. anda. 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 las ll llam amad adas as a las las op oper erac acio ione nes s so son n mu muy y se segu guid idas as,, el se serv rvic icio io pu pued ede e 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  (wsdl2jolie wsdl2jolie). ). También existe este ticket en el trac de vtiger  vtiger   utilización de Jolie de Jolie ( referente a este asunto. asunto. El err error or 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 obtenemos el siguiente mensaje de error: 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 include/We /Webse bservi rvices ces/Au /AuthT thToke oken.p n.php hp

(re (revis visión ión: : 371 3711) 1)

+++ includ include/W e/Webs ebserv ervice ices/A s/Auth uthTok Token. en.php php

(co (copia pia de trab trabajo ajo) )

@@ -18,6 +18,14 @@   $servertime = time();  

$expireTime = time()+(60*5);

+ $sql = "select u us serid,token,expiretime,count(*) a as s c co ount f fr rom 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 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

Login inicia  inicia una sesión de cliente con el servidor, autentifica el La operación de Login 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 Challenge nos  nos permitirá obtener una clave de desafío como La operación Get Challenge se ve en el siguiente ejemplo.

- 17 -

 

Login de   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 Login 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.

- 18 -

 

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

List Types Types proporciona  proporciona una lista de módulos disponibles. Esta lista La operación List Types 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.

Describe Describe proporciona  proporciona información detallada de un módulo, tanto La operación Describe 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.

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

Operaciones de cambio en la aplicación (CRUD) El API pro propor porcio ciona na ope operac racion iones es par para a crear, crear, rec recupe uperar rar,, act actual ualiza izarr y eli elimin minar ar objetos de la aplicación.

Crear Crea un nuevo registro en la aplicación.

Ejemplo 1 Create,, en El sig siguie uiente nte eje ejempl mplo o cre crea a un con contac tacto to utiliz utilizand ando o la operación de Create este est e cas caso o los campo campos s obl obliga igator torios ios son lastname  y assigned_user_id. El valor devuelto $savedObject  es  es un array que contiene los campos del nuevo objeto creado, incluyendo un identificador que se puede utilizar para identificar el nuevo registro.

- 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 correspondient e en el contacto. Para poder obtener el identificador disponemos Query (ver  (ver ejemplos). Para este ejemplo vamos a suponer que de la operación Query hemos ejecutado esta operación para obtener el identificador de la cuenta con nombre vtiger y hemos obtenido 3×2.

Obtener Obtene Obte nerr lo los s va valo lore res s de un regi regist stro ro ex exis iste tent nte e en la ap apli lica caci ción ón.. Po Pode demo mos s Retrieve.. Esta recuperar un objeto utilizando su identificador y la operación de Retrieve operación nos devuelve una array con todos los campos leídos. Los campos de tipo referencia contiene un identificador de objeto y objeto  y siempre habrá un campo objeto del  del registro recuperado. especial Id que será el identificador de objeto En el ejemplo recuperamos el objeto con identificador 3×2.

Actualizar Actualiza Actual iza 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 ejemp lo de de creac creación. En ese yejemp ejemplo, en la secuencia que estoy ejecutando doha el desarrollo losión. ejemplos en lalo,instalación de prueba que ejecutan tengo, se asignado asign ado al conta contacto cto el ident identificad ificador or 4×19 4×194. 4. Una prueba interesante interesante es edita editarr unos un os ca camp mpos os de es este te regi regist stro ro de dent ntro ro de la ap apli lica caci ción ón y ve veri rifi fica carr co como mo se pierden esos valores tras la ejecución del siguiente ejemplo.

Eliminar Conemo n mos la sope operac ración ión deta Del Delete ete    se pued ede ede elim el imin inar cual alqu quie ier rsult re regi gist stro al que e te tene ac acce ceso so. . Esta Es op oper erac ació ión n pu no devu vuel elve vear ning nicu ngún ún re resu ltad ado orosa salv lvo oqu el estandar indicando si se ha podido eliminar o no el registro indicado.

Operaciones de Consulta ión de Con Consul sulta ta   perm permit ite e inte interr rrog ogar ar la ap apli lica caci ción ón en busc busca a de La operac operación 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. Consulta. El primer ejemplo obtiene todos los contactos a los que tiene acceso el usuario conectado.

El siguiente ejemplo aplica un condicional a la consulta y obtiene aquellos contactos con apellido “Valiant”.