Creación paso a paso de un webscript Alfresco

1
12160

Creación paso a paso de un webscript Alfresco

Índice de contenidos

1. Introducción
2. Entorno
3. Estructura de un webscript
4. Despliegue de un webscript
5. Conclusiones
6. Referencias

1. Introducción

¿Qué son los webscripts en Alfresco?

Ya comentamos algo relacionado con webscripts en el tutorial creación de un módulo AMP de Alfresco con arquetipo Maven,
en el cual nos basaremos para la creación de un webscript a partir de un módulo AMP ya existente. Si no sabes lo que es un módulo AMP, o un aspecto en Alfresco, te recomendamos que realices el tutorial anterior antes de continuar con éste.

Un webscript no es más que un servicio REST que responde a todos los métodos HTTP y que permite extender el catálogo de servicios que proporciona nuestra
distribución de Alfresco.

¿Qué tipo de webscripts hay?

Hay dos tipos, principalmente:

  • Webscripts de datos: Son aquellos que consultan, modifican y retornan datos de Alfresco (documentos), ofreciendo una interfaz para consumir dicho servicio por terceros (es el que realizaremos en este tutorial)
  • Webscripts de presentación: Dichos webscripts modifican o extienden la capa de presentación de Alfresco; Podrán definir nuevos componentes en su interfaz de usuario, definir portlets, crear un website dentro de Alfresco, etc.

A continuación se muestra la definición de la arquitectura de webscripts en Alfresco

Como se puede apreciar, se aplica el patrón MVC para los webscripts en Alfresco. Más adelante en este tutorial definiremos los archivos que cumplen el patrón y que son necesarios y suficientes para definir nuestro propio webscript. No entraremos más en detalle en la arquitectura por ahora.

¿Cuándo tendrá sentido desarrollar nuestro propio webscript?

Tendrá sentido desarrollarlo principalmente cuando no tengamos ningún servicio en nuestro catálogo de servicios de Alfresco que cubra nuestras necesidades de negocio.
Esto ocurrirá muy a menudo, ya que basta que tengamos campos (meta-información) asociada a nuestros documentos en Alfresco (ya sea mediante la definición de tipos de contenido
o aspectos), para que necesitemos retornarlos en un servicio para, por ejemplo, ser explotados en otra aplicación.

Otro posible caso de uso puede ser hacer un uso personalizado de las búsquedas que ofrece Alfresco o Lucene. Personalizar el tipo de búsqueda, fijar el número de
resultados, usar una plantilla (explicaremos más adelante qué son las plantillas), definir un nuevo formato de respuesta, etc., son algunos de los criterios que pueden ser la causa de querer desarrollar nuestro
propio webscript en Alfresco.

Un caso menos común pero que también se puede dar es cuando queremos extender la interfaz de usuario con nuevos componentes visuales que necesitemos crear.

2. Entorno

  • Macbook pro core i7 con 16gb RAM
  • SO: Mavericks
  • IDE: Spring Tool Suite 3.4.0 RELEASE
  • Apache Maven 3.1.1

3. Estructura de un webscript

En este tutorial vamos a desarrollar un webscript en Javascript. El webscript hará una búsqueda en Alfresco para encontrar documentos que cubran los requisitos de negocio
planteados en el anterior tutorial (empresa y departamento).

Existe la posibilidad de desarrollar webscript en Java, para más información sobre el API que ofrece
Alfresco sobre el desarrollo de webscripts en Java, consultar estos dos enlaces: https://wiki.alfresco.com/wiki/Java-backed_Web_Scripts_Samples y https://wiki.alfresco.com/wiki/Services_Framework.

Vamos pues a desarrollar un webscript en nuestro módulo AMP, escrito en Javascript. Antes de abordarlo, comentaremos la estructura del mismo.
Un webscript se compone principalmente de tres archivos:

  • Un archivo descriptor del servicio
  • Un archivo Javascript con la funcionalidad del mismo
  • Una plantilla Freemarker con el formato de la respuesta del servicio

Archivo descriptor

Este archivo contendrá una serie de propiedades que corresponde con información básica del servicio, como su nombre, endpoint, formato de respuesta, autenticación, etc.

El formato del nombre de este archivo (que debe cumplirse a rajatabla si queremos que se reconozca como webscript de Alfresco), es <nombre_servicio>.<método_http>desc.xml .
Un ejemplo sería: search.get.desc.xml

El contenido del archivo a modo de ejemplo es el que mostramos a continuación:


<webscript>
  <shortname>Text Search</shortname>
  <description>Searching department data</description>
   <url>/myCompany/searchDepartmentData?q={departmentData?}</url>
   <format default="json">extension</format>
   <authentication>user</authentication>
</webscript>

En el ejemplo anterior, indicamos que se trata de un servicio de búsqueda de datos de departamento de una empresa (continuando con el ejemplo del tutorial anterior),
la URL del endpoint del servicio, donde se recibe un parámetro departmentData opcional, que el formato de respuesta será JSON y que la autenticación es de usuario (que tendremos que pasar como cabecera de la request
si queremos llegar a consumir el servicio)

Archivo Javascript (Controlador)

Se desarrolla en este archivo la lógica del servicio, tal y como comentamos antes, en Javascript. El API que nos ofrece Alfresco para el desarrollo de webscripts en Javascript se
encuentra http://wiki.alfresco.com/wiki/4.0_JavaScript_API.

El formato del nombre de este archivo es <nombre_servicio>.<método_http>.js (de nuevo obligatorio para una correcta definición del servicio). En nuestro ejemplo sería: search.get.js

Siguiendo con el ámbito de negocio de búsqueda departamental, un ejemplo de este archivo sería el siguiente:


const DEFAULT_MAX_RESULTS = 500;

function doSearch(textArg, maxResults)
{

    var alfQuery = textArg;
    
    var queryDef = {
        query: alfQuery,
        language: "fts-alfresco",
        page: {maxItems: maxResults},
        templates: []
    };

    return search.query(queryDef);
}

function main()
{
    var textArg = args.q;
    var maxResults = (args.maxResults !== null) ? parseInt(args.maxResults) : 
        DEFAULT_MAX_RESULTS; 

    var nodes = doSearch(textArg, maxResults);

    model.nodes = nodes;
}

main();     

El ejemplo anterior consta de una búsqueda genérica, que cubriría las necesidades de negocio de búsqueda por metadatos de los departamentos de nuestra empresa.
Consta de un método main(), que define un número máximo de resultados (para evitar resultados de búsqueda demasiado grandes) e invoca al método doSearch(..), que
realiza una búsqueda FTS -Full Text Search- (para más información sobre las búsquedas FTS: https://wiki.alfresco.com/wiki/Full_Text_Search_Query_Syntax) con la query que le pasamos por parámetro (nuestro departmentData).

Una plantilla Freemarker con el formato de la respuesta del servicio (Vista)

Por último y no menos importante, el archivo con el formato de la respuesta de nuestro servicio contendrá una plantilla compilada con FreeMarker (para más información sobre
el sistema de plantillas FreeMarker consultar http://freemarker.org/). El formato de respuesta puede estar en varios lenguajes permitidos por Alfresco y FreeMarker: JSON, XML, HTML, y algunos más.
En nuestro caso, el formato del body de la response de nuestro servicio será JSON.

El formato del nombre del archivo (de nuevo obligatorio) deberá ser <nombre_servicio>.<método_http><formato_respuesta>.ftl , en nuestro ejemplo sería search.get.json.ftl

Un ejemplo de respuesta para nuestro problema de departamentos es:


<#assign idDpto = "{dptoEmpresaModel.model}idDpto">

{ "result": [
  
  <#list nodes as node>
  {
    "id" : "${node.id}",
    "name" : "${node.name}",

    <#if node.properties[idDpto]?exists>
        "departmentId" : "${node.properties[idDpto]}"
    </#if>

  }

  <#if node_has_next>,</#if>

  </#list>

 ]
}

En el ejemplo anterior, se recorre la lista de nodos (documentos) encontrados en Alfresco, para mostrar el ID interno de Alfresco, el nombre del documento,
y el ID de departamento que se obtiene de la lista de propiedades (o metadatos) del documento, si existe.

4. Despliegue de un webscript

Una vez tenemos definido y desarrollado nuestro webscript, es hora de desplegarlo. Existen dos formas de desplegar un webscript:

  • Instalando el servicio en un módulo AMP de Alfresco
  • Mediante la propia aplicación de Alfresco (o Share)

Instalando el servicio en un módulo AMP de Alfresco

Esta forma de despliegue permite tener agrupados todos nuestros webscripts en uno o varios módulos AMP de Alfresco. Con esto podemos tener nuestro catálogo de servicios
de forma centralizada. No obstante, a la hora de realizar pruebas, es posible que sea una solución más tediosa, ya que será necesario redesplegar los módulos implicados en el cambio en nuestra distribución de Alfresco.
Precisamente esta desventaja será la ventaja de la siguiente solución, como veremos a continuación.

No obstante, recomendamos esta solución cuando tenemos una versión final de nuestros servicios.

Instalar un webscript en nuestro módulo AMP de Alfresco es muy sencillo. Simplemente hay que copiar los tres archivos descritos anteriormente en una estructura de carpetas específicos del módulo, para que
Alfresco pueda leerlo e incluirlo como servicios de nuestra distribución. En concreto, la carpeta donde deben ir nuestros archivos descriptores de webscripts será:

<directorio_amp>/config/alfresco/extension/templates/webscripts/<paquete_base_servicios>

Siguiendo el ejemplo de empresa/departamento:

amp/config/alfresco/extension/templates/webscripts/com/autentia/tutoriales/

En esta carpeta se añadirán los tres archivos descritos anteriormente:

  • search.get.desc.xml
  • search.get.js
  • search.get.json.ftl

Desplegamos el AMP en Alfresco, et voilà!, ya tenemos nuestro servicio desplegado y totalmente disponible en el catálogo de servicios de nuestra distribución del Alfresco.

Instalando el servicio mediante la propia aplicación de Alfresco (o Share)

Otro método de despliegue de un servicio en Alfresco es mediante la subida de los tres ficheros descriptores del mismo a la propia aplicación de Alfresco o Share (en este tutorial usaremos la de Alfresco).
Mediante este procedimiento, podremos disponer de nuestro servicio de forma mucho más rápida (no hay más que subir los archivos con la aplicación y refrescar el catálogo de servicios), por lo que es una buena solución
cuando estamos desarrollando y/o probando nuestro servicio, ya que vamos a requerir de subidas continuas para testear que todo está correcto. Pero no lo recomendamos como solución final de despliegue, ya que implica que tengamos
distribuidos los scripts por la consola, siendo más complejo de mantener y catalogar.

Para desplegar el servicio mediante la aplicación de Alfresco, tendremos que seguir los siguientes pasos:

  • 1. Entrar en la aplicación de Alfresco (para una distribución en local con los parámetros por defecto: http://localhost:8080/alfresco)
  • 2. Desde el espacio ‘Company Home’, acceder a ‘Diccionario de datos’ -> ‘Extensiones de Web Scripts’
  • 3. En este directorio crearemos una jerarquía de espacios correspondiente a nuestro paquete base de servicios en el AMP. Este paso no es obligatorio (podríamos desplegar los servicios en el espacio padre),
    pero vamos a mantener la jerarquía de carpetas para una correcta organización de los servicios. Crearemos por tanto: com/autentia/tutoriales

  • 4. Añadiremos a continuación los archivos de nuestro servicio:

  • 5. Por último necesitamos actualizar el catálogo de servicios de Alfresco, para que instale nuestro nuevo webscript. Para ello:
    • 5.1. Accedemos a la URL http://localhost:8080/alfresco/service/index . Aquí se muestra el catálogo de servicios de nuestra distribución de Alfresco. Recomendamos echar una ojeada al contenido de estas páginas para estar al tanto de los servicios de los que dispone Alfresco 😉

    • 5.2. Hacemos clic sobre el botón ‘Refresh Web Scripts’. Se nos mostrará a continuación una pantalla con el resumen de servicios instalados. Comprobamos que el número actual de servicios ha aumentado en uno 🙂

Ya tendremos instalado nuestro nuevo servicio en Alfresco.

5. Conclusiones

Podemos extender la funcionalidad de Alfresco de forma muy sencilla mediante la definición de servicios o webscripts (si no encontramos la funcionalidad deseada de entre los más de 500 servicios que ya ofrece Alfresco en sus distribuciones), aprovechando la potencia que nos ofrecen los distintos APIs del producto,
para cubrir las distintas necesidades de nuestro negocio.

6. Referencias

  • https://wiki.alfresco.com/wiki/Java-backed_Web_Scripts_Samples
  • https://wiki.alfresco.com/wiki/Services_Framework
  • http://freemarker.org/
  • http://wiki.alfresco.com/wiki/4.0_JavaScript_API
  • https://wiki.alfresco.com/wiki/Full_Text_Search_Query_Syntax

1 COMENTARIO

DEJA UNA RESPUESTA

Por favor ingrese su comentario!

He leído y acepto la política de privacidad

Por favor ingrese su nombre aquí

Información básica acerca de la protección de datos

  • Responsable:
  • Finalidad:
  • Legitimación:
  • Destinatarios:
  • Derechos:
  • Más información: Puedes ampliar información acerca de la protección de datos en el siguiente enlace:política de privacidad