Webscripts en Alfresco ECM

Los WebScripts son elementos clave dentro de Alfresco y de uso obligado para cualquier desarrollador. Nos permiten construir servicios web para la gestión de contenidos accesibles vía HTTP, es decir, convierten el repositorio de Alfresco en un gestor de contenido controlador mediante un servidor HTTP. Se crean de forma muy rápida, usan JavaScript y Freemarker para ofrecen máxima flexibilidad y velocidad de despliegue. Pasamos a describir a continuación qué son y cómo crearlos.

Introducción

Un Webscript es algo tan simple como un servicio mapeado a una URI que responde ante peticiones HTTP de tipo GET, POST, PUT y DELETE. Es por eso, que el desarrollo de Web Scripts nos permite construir fácilmente Servicios Web para gestión de contenidos identificados por una URI y accesibles vía HTTP, es decir, integraciones REST.

Podemos acceder, manejar y enlazar nuestros contenidos a través de una API tipo REST. No necesitamos herramientas especiales ni conocimientos de Java. Todo lo que necesitamos es un editor de texto o el cliente web Alfresco Explorer o Share: sin compilaciones, paradas de servidor ni complejas instalaciones.

Podemos diferenciar entre dos grandes familias de Web Scripts:

• Webcripts de datos: encapsulan el acceso o modificación del contenido/datos del repositorio, por lo tanto, son expuestos siempre y sólo por el servidor repositorio de Alfresco. Proveen una interfaz del repositorio a aplicaciones cliente. Los procesos suelen utilizar documentos en distintos formatos (XML, JSON, etc.). Alfresco incluye por defecto Web Scripts de datos que sirven para: añadir tags a los documentos, actividades, gestión del site, etc.
• Webscripts de presentación: Permiten construir interfaces de usuario como dashlets para Alfresco, portlets para un portal que siga el estándar JSR-168, componentes UI como Alfresco SURF, un sitio Web o una aplicación a medida. Generalmente renderizan HTML. Pueden ser desplegados en un servidor Alfresco o en un servidor independiente. Cuando se escoge esta última opción, interactuan con los Data Web Scripts. Por defecto existen los Web Scripts para Portlets, integración con Office, Componentes SURF, etc.

La interfaz de un Webscript está formada por:

• URI,
• Métodos HTTP y
• Tipos de documento.

Estos elementos son la única información que deben conocer los clientes.

Elementos importantes de un Webscript

Un Webscript está formado principalmente por tres elementos:

• Un documento de descripción:  identifica la URI que instancia el script, un nombre corto, descripción y requisitos de autenticación y transacciones.
• Un script que actúa de controlador opcional. Escrito en Javascript puede realizar tareas como consultas al repositorio de Alfresco, actualizar el repositorio, etc. El script tiene acceso a todos los argumentos de la URI, a los servicios de Alfresco y a los datos del repositorio.
• Una o más plantillas de respuesta FreeMarker denominadas vistas. Se encargan de renderizar la respuesta en el formato adecuado: HTML, ATOM, XML, RSS, JSON, CSV,  o cualquier combinación de ellos.

Por lo tanto, el diseño de un webscript implica la creación de cada uno de estos elementos.

Documento de descripción

Este fichero no es más que un fichero de texto plano cuya extensión debe ser .desc.xml, de esta forma se informa a Alfresco que dicho documento es una descripción de Webscript. Por ejemplo org/alfresco/ejemplo/webscript.get.desc.xml define (configuración por convención).

• Un paquete org/alfresco/ejemplo.
• Un id de servicio holamundo.
• Un enlace al método GET de HTTP.

Su contenido podría ser:

<webscript>
<shortname>Hola Mundo</shortname>
<description>Saludo a usuario</description>
<url>/holamundo?to={name?}</url>
<format default="html">extension</format>
<authentication>user</authentication>
</webscript>

• shortname: nombre corto del Webscript.
• description: (opcional) es la documentación del Webscript.
• url: (una o más) es la plantilla de una URI asociada al Webscript. No es necesario registrar todas las posibles variaciones de la plantilla, aunque, son muy útiles desde el punto de vista de la documentación.

Se muestran algunos ejemplos:

/content/a/b/c/d.txt
/sample/helloworld?to={name?}
/blog/search?q={searchTerm}&n={numResults}
/people/{personName}/profile/{profileStyle}
/blog/category/{category}?n={itemsperpage?}
/user/{userid}

Plantillas

La plantilla es responsable de generar la respuesta del webscript. Puede generarse en diferentes formatos. La generación de plantilla para Webscript implica el conocimiento del lenguaje Freemarker. El siguiente ejemplo es una plantilla que muestra las propiedades de un documento en el repositorio de Alfresco:

<table>
<#assign props = document.properties?keys>
<#list props as t>
<#-- If the property exists -->
<#if document.properties[t]?exists>
<#if document.properties[t]?is_date>
<tr><td>${t} = ${document.properties[t]?date}</td></tr>
<#elseif document.properties[t]?is_boolean>
<tr><td>${t} = ${document.properties[t]?string("yes", "no")}</td></tr>
<#else>
<tr><td>${t} = ${document.properties[t]}</td></tr>
</#if>
</#if>
</#list>
</table>

Script controlador

Un Web Script puede opcionalmente ejecutar JavaScript en la invocación de su URI. Este JavaScript puede lanzar consultas o actualizar el repositorio. También puede construir un modelo de datos que, posteriormente, podrá ser utilizado por la plantilla que generará la respuesta.

El nombre del fichero sigue la siguiente sintaxis:

<serviceId>.<httpMethod>.js

Por ejemplo, para el servicio Hola Mundo podemos crear un fichero en la misma carpeta que el documento de descripción holamundo.get.js

Hola ${args.nombre}, te has identificado como ${person.properties.userName}.

Conclusión

Hemos presentado de forma muy sencilla el concepto de Webscript en Alfresco, si quieres profundizar en el tema puedes acceder a la wiki de Alfresco o esperar a nuestros próximos post.

Seminario gratuito sobre Alfresco

Al hilo de este post, nos gustaría informaros de que el próximo 21 de octubre celebramos un seminario gratuito sobre Alfresco. Será de 09:00 a 14:30 horas y contaremos con la exposición de un caso de éxito de Vodafone España. Las inscripciones ya están abiertas. Consulta el programa y apúntate.