Differences

This shows you the differences between two versions of the page.

--- en:devel:corebosws:docenhance_examples [2014/05/18 17:28]
joebordes
+++ en:devel:corebosws:docenhance_examples [2020/11/04 00:37] (current)
joebordes [Create, Update and Retrieve Images]
@@ Line 1: / Line 1: @@
-====== Webservice: Working with Documents ======
+====== Webservice: Working with Documents and Images ======
-=====Create, Update and Retrieve=====
+=====Create, Update and Retrieve Documents=====
-The purpose of these enhancements are to permit uploading files when we create/update documents through the webservice interface. This extension also adds functionality that permits establishing relationships with other entities to the document we are creating/editing.
+The purpose of these enhancements are to permit uploading files when we create/update documents through the web service interface. This extension also adds functionality that permits establishing relationships with other entities to the document we are creating.
-Calls to REST methods of Create, Retrieve Update and maintain your profile. This extension adds to calls special fields, but if no calls are modified to maintain consistency with all interface and change less code base.
+Calls to REST methods of Create, Retrieve and Update maintain their profile and keep working as before. This extension adds to these calls a set of special fields that will be acknowledged by the enhancements.
-Las llamadas a los métodos REST de Create, Update y Retrieve mantienen su perfil. Esta extensión añade unos campos especiales a las llamadas, pero las llamadas en si no se modifican para mantener la consistencia con todo el interface y modificar menos código base.
-Los campos especiales que se reconocen por esta extensión son:
+The special fields are:
-^relaciones| es una lista de identificadors de registros separadas por comas.|
+^relations| a comma separated list of webservice identifiers.|
-^filename| <code>es un array con los campos:
+^filename| <code>array with these fields:
-  name: texto, nombre fichero a subir,
+  name: string, name of the file to upload,
-  size: filesize(fichero)
+  size: file size
-  type: filetype(fichero)
+  type: file type
-  content: base64_encode(fichero)</code>|
+  content: base64_encode(file)</code>|
+With the virtual field **relations** we can establish relationships between the document and any other record. For example, we can upload a document and automatically relate it with a trouble ticket (HelpDesk).
+Since a document can be related to many other records, the **relations** parameter is a comma-separated list of entities. The document being created will be related to all of them.
+This new **relations** field will also be returned when executing a Retrieve. The format will be a comma-separated list of related entities.
-Mediante el campo virtual **relaciones** conseguimos que el documento cread quede automáticamente relacionado con otras entidades, por ejemplo, nos permite crear un documento directamente relacionado con una incidencia.
+To permit uploading documents we have added another virtual field called **filename**. It is an array with the four values we need to upload an attachment:
+  * name: name of the attachment in the application
+  * size: size of the file being sent
+  * type: type of the file being sent
+  * content: base64 encoded string with the full contents of the file
-Dado que un documento puede estar relacionado con muchos registros, este parámetro es una lista de [[vtwsintroduccion#id_format|identificadores]] de registro. El documento creado/actualizado se relacionará con todos los registros de la lista.
+As of **coreBOS 5.6** you will also receive another virtual field when retrieving a document record. This field is called **_downloadurl** and represents the absolute path of the file attachment in the application. This will permit easy linking from external applications and websites. This functionality is especially useful for e-commerce sites.
-De igual manera, si estamos ejecutando un Retrieve, este nuevo campo virtual se devolverá con el formato indicado.
+This virtual field is also added to the query language when it is possible.
-Para permitir enviar ficheros físicos al documento hemos añadido otro campo virtual denominado **filename**. Es un array con los cuatro valores que precisamos para crear el documento:
+<WRAP center round info 60%>the **_downloadurl** virtual field will only be present in documents with a file location type of Internal</WRAP>
-  * name: el nombre del documento en el sistema
-  * size: el tamaño del fichero enviado
-  * type: el tipo mime del fichero enviado
-  * content: el fichero en si mismo, este parámetro es una codificación base64 de todo el contenido
-Aquí se pueden ver unos ejemplos de llamadas a esta nueva funcionalidad:
+Next, you can find some examples.
@@ Line 36: / Line 41: @@
 <code php>
 <?php
-include_once('vtwsclib/Vtiger/WSClient.php');
+include_once('cbwsclib/WSClient.php');
 require_once 'debugoutput.php';
-$url = 'http://localhost/parkare/webservice.php';
+$url = 'http://localhost/corebos/webservice.php';
 $wsClient = new WSClient($url);
 // Login
@@ Line 72: / Line 77: @@
 	'filestatus'=>1,
 	'folderid' => '22x1',
-	'relations' => '9x66873',  // además de crear el documento con el adjunto lo dejará relacionado con este registro
+	'relations' => '9x66873',  // besides creating the document it will relate it to this record
 );
@@ Line 93: / Line 98: @@
 <code php>
 <?php
-include_once('vtwsclib/Vtiger/WSClient.php');
+include_once('cbwsclib/WSClient.php');
 require_once 'debugoutput.php';
-$url = 'http://localhost/parkare/webservice.php';
+$url = 'http://localhost/corebos/webservice.php';
 $wsClient = new WSClient($url);
 // Login
@@ Line 127: / Line 132: @@
 	'folderid' => '22x1',
 	'id' => '7x134089',
-	'relations' => '3x1151',
+	// 'relations' NOT SUPPORTED ON UPDATE: use set_relations webservice call
 );
@@ Line 197: / Line 202: @@
       'note_no' => string 'DOC5379' (length=7)
       'id' => string '7x134063' (length=8)
-      'relations' => !!!  ESTE ES NUEVO !!!
+      'relations' => !!! THIS IS NEW !!!
         array
-=> string '9x66873' (length=7)   !!! Esta relacionado con el registro 66873 de la entridad 9 !!!
+=> string '9x66873' (length=7)   !!! related to record 66873 of the entity 9 !!!
+      '_downloadurl' => string 'http://localhost/coreBOSwork/storage/2014/August/week2/134063_1.jpg' (length=64)
 </code>
-=====Retrieve Attachment=====
-Este nuevo método REST devuelve la codificación base64 del fichero adjunto al documento dado. Esta llamada se añade con dos objetivos, no cargar la obtención de una lista de documentos con sus ficheros adjuntos siempre, lo que haría que el Retrieve fuera demasiado lento debido a que mandaría documentos enteros cuando solo necesitamos una lista, y para no tener que modificar el interface del método Retrieve para permitir pasar un parámetro adicional que indicara si se requiere enviar el adjunto o no.
+====Retrieve Attachment====
-El **perfil** del método es
+This new REST method returns the base64 encoded file attached to the given document. This call is added with two goals in mind, to obtain information of the attachment of a document without downloading the whole file which would slow many operations, and to no have to add yet another virtual field to the native Retrieve operation to indicate if we want to receive the whole file or not.
+The **profile** of the method is
 <code>retrievedocattachment(id:Id,returnfile:boolean):Map</code>
-Donde los **parámetros** son
+^id| a comma-separated list of document identifiers of which we want to get the attachments|
-^id| una lista de [[vtwsintroduccion#id_format|identificadores]] de documentos a obtener separados por comas|
+^returnfile| 1 if we want the whole file, 0 if we just want the attachment information|
-^returnfile| 1 si queremos que nos devuelva el fichero, y 0 si solo devuelve los detalles del fichero|
-La **respuesta** es un objeto [[vtwsintroduccion#map|Map]] con los campos del adjunto al documento. Para cada identificador dado se devolverá un array con la estructura siguiente:
+The **response** is an object with the fields of the attachment. For each given identifier we will get an array with this structure:
 ^filename| <code>is an array with the fields:
@@ Line 218: / Line 224: @@
   size: file size
   type: file type
-  content: base64_encode(file)</code>|
+  attachment: base64_encode(file)</code>|
 If the parameter **returnfile** is 0, the field **content** will be empty (no file sent, reducing bandwidth usage and time)
-Find next example code of a call to this method followed by the resulting output.
+Find next an example code of a call to this method followed by the resulting output.
 ** Example Code of Call**
@@ Line 267: / Line 273: @@
 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
+show a progress meter as a file downloads. The content-lenght can be determined by
 filesize function returns the size of a file.
 */
@@ Line 282: / Line 288: @@
 array
-  'url' => string 'http://localhost/parkare/webservice.php' (length=39)
+  'url' => string 'http://localhost/corebos/webservice.php' (length=39)
   'code' => int 200
   'headers' =>
@@ Line 312: / Line 318: @@
 </code>
+=====Create, Update and Retrieve Images=====
+Following a similar approach as the **filename** virtual field added for uploading document files, we have added also a generic virtual field to all the other modules in the application named **attachments**.
+**attachments** is an array of file information for each image field contained in a module where you want to upload a file and can be used in Create, Update and Revise operations.
+Let's suppose that you have two image fields on a module named cf_998 and cf_999. You can upload files to these two fields with an array like this:
+<code PHP>
+$recordInfo = array(
+	...other fields in the record...
+	'cf_998' => 'barcode',
+	'cf_999' => 'somename',
+	'attachments' => array(
+		'cf_998' => array(
+			'name'=>'barcode',  // no slash nor paths in the name
+			'size'=>strlen($file_data),
+			'type'=>'image/png',
+			'content'=>base64_encode($file_data)
+		),
+		'cf_999' => array(
+			'name'=>'somename',  // no slash nor paths in the name
+			'size'=>strlen($file2_data),
+			'type'=>'application/pdf',
+			'content'=>base64_encode($file2_data)
+		),
+	),
+	...other fields in the record...
+);
+</code>
+A normal Retrieve call on a record with images will return the information of the file; the name, the location on disk (URL), and some other metadata in a virtual field with the same name of the field followed by "imageinfo", but we have also added a method in order to retrieve file information of a record.
+getRecordImages allows a web service client to retrieve the information of the image attachments associated with a record, which can then be used with the build/HelperScripts/getImageData.php script to obtain the image data itself.
+^Method:|**getRecordImages**|
+^Purpose:|Returns an array of file information for each image field of a module.|
+^Profile:|getRecordImages(id:string):Map|
+^Send as:|GET|
+^Parameters:| => id: web service id of the record with image fields we want to get.|
+^Response:|an array with: name, path, URL, type, internal ID, for each file in the record|
+Examples:
+  * [[https://github.com/tsolucio/coreBOSwsDevelopment/blob/master/testcode/438_createWithImage.php|Create with Image]]
+  * [[https://github.com/tsolucio/coreBOSwsDevelopment/blob/master/testcode/438_updateWithImage.php|Update with Image]]
+  * [[:en:devel:updateimagefield|How to update an image field from code]]
+==== Product Multi-Image field====
+The product module contains a special, non-standard image field which may contain many images. coreBOS does not recommend the use of this field. Individual images should be used instead.
+When calling Retrieve on a product the first image found in the multi-image field will be returned. It is NOT guaranteed to always get the same image.
+You can use the **addProductImages** method to insert images in this field.
+^Method:|**addProductImages**|
+^Purpose:|Inserts a set of images into the Product multi-image field|
+^Profile:|addProductImages(id:string, files:Map):Map|
+^Send as:|POST|
+^Parameters:| => id: web service ID of the product record to upload the images to \\ => files: an array of images to upload, each array entry must contain two fields: name and content (base64 encoded)|
+^Response:|an array with information of the executed operations|
+----
+<WRAP right>
+[[:en:devel:corebosws:getpdfdata|Next: GenDoc and PDF output]] | [[en:devel:corebosws:tableofcontents|Table of Contents]]
+</WRAP>
+----

User Tools

Differences

Page Tools

Site Tools