Web Scripts en Alfresco

AGENDA
• Definición del Framework Alfresco Web
Scripts.
• Arquitectura del Framework Web Scripts.
• Construcción de un API RESTful usando
Web Scripts (Java y JavaScript)
– Desarrollar Componentes Web Scripts de tipo GET.
– Desarrollar Componentes Web Scripts de tipo
POST.
 Introducción a Alfresco Web Scripts

Introducción al Framework
Alfresco Web Scripts
 Introducción al Framework Alfresco Web Scripts

• Web Scripts proporcionan una forma

amigable de acceder los recursos del
repositorio a través de comandos HTTP.
• De esta forma los programadores pueden
desarrollar una API RESTFul
personalizadas para accesar, manejar y
enlazar contenido del repositorio.
 Introducción al Framework Alfresco WebScripts

• Una aplicación externa podría realizar una

HTTP a Alfresco que especifique una
referencia a un nodo y a una plantilla
FreeMarker que devuelva XML o JSON.
Alfresco procesara la plantilla en el contexto
del nodo especificado y devolverá el
resultado.
 Introducción al Framework Alfresco Web Scripts

• Se pueden usar Web Scripts para exponer el

contenido del repositorio de Alfresco a
través de una API RESTful para:
– Proveer al repositorio de Alfresco de servicios de
contenidos que serán accesibles para todo el mundo.
– Consultar en el repositorio, extraer contenido y alterar
su comportamiento.
– Exponer el repositorio para realizar gestión
documental o gestión de contenidos web.
– Proveer de facilidades de búsqueda personalizadas.
– Crear ATOM o RSS feeds para los contenidos del
repositorio o procesos de negocio.
 Alfresco WebScripts - Características

CARACTERISTICAS
– Web Scripts ahora es un componente independiente
capaz de acoger otros Web Scripts en otros niveles del
Repositorio de Alfresco.
– Ahora URI Templates cumplen con JSR-311 (JAX-RS).
– Posibilidad de que pueda ejecutar un usuario
especifico el Web Script.
– Posibilidad de personalizar Web Scripts con una
configuración Web Script especifica.
– Acceso a las cabeceras de Respuesta.
– Procesar las solicitudes realizadas en el Body.
– Capacidad de Categorizar WebScript por familias.
 Arquitectura de Alfresco Web Scripts

Arquitectura del Framework

Alfresco Web Scripts
 Arquitectura Framework Alfresco Web Scripts

• Los Web Scripts se enlazan a una URL

determinada y responde a métodos HTTP
(GET/POST/PUT/DELETE)
• Los Web Scripts se Categorizan en:
– Orientados a los Datos.
– Orientados a la Presentación
Alfresco Web Scripts - Arquitectura JavaScript
 Arquitectura Framework Alfresco Web Scripts

• Al Framework de Web Scripts sigue el patrón

Vista Controlador (MVC)
– El Controlador será JavaScript en el servidor, un
Bean de Java o ambos. Manejará las peticiones,
realizará cualquier lógica de negocio que se
necesite, alimentará al Modelo con datos y
reenviará la petición a la vista.
– Manejará las peticiones, realizará cualquier lógica
de negocio que se necesite, alimentará al Modelo
con datos y reenviará la petición a la vista.
– El Modelo básicamente es una estructura de datos
que se intercambian Vista y Controlador.
 Arquitectura Framework Alfresco Web Scripts

• La accesibilidad URL al controlador se hace con

un descriptor XML que es responsable de
declarar el patrón URL, de si el script requiere
una transacción o no y de los requisitos de
autenticación para el script.
• Los formatos de respuesta son mapeados hacia
las plantillas FreeMarker usando convenciones de
nombres. Así, por ejemplo, la plantilla
FreeMarker que devuelve informes en HTML se
llamara con una extensión de html (xxx.html.xxx)
mientras la que lo haga en XML se llamará con
una extensión de xml (xxx.xml.xxx).
 Arquitectura Framework Alfresco Web Scripts

• Alfresco ofrece por defecto una API con Web

Scripts construidos sobre esta plataforma de
web scripts. Los principales objetivos de
diseño de esta API son la facilidad de
comprensión y uso, la minimización de las
herramientas necesarias por parte del cliente,
soportar el acceso remoto, soportar el acceso
a múltiples repositorios, mantenerse en línea
con los estándares REST, facilitar la
actualización y ampliación de servicios y cubrir
el 100% de los servicios del Repositorio.
Alfresco Web Scripts - Arquitectura Java
 Construcción una API Alfresco Web Scripts

Construcción de un API Rest

usando Web Scripts
 Construcción de una API con Alfresco Web Scripts

• Para crear Web Scripts se requiere:

– Crear los Archivos Necesarios. (Controlador,
Plantillas, Descriptor)
– Instalar estos archivos en una locación
determinada de Alfresco.
– Registrar los nuevos Web Scripts.
– Correr estos Web Scripts desde su Browser.
 Construcción de una API con Alfresco Web Scripts

• Componentes de un Web Scripts

– Archivo descriptor
– Una o mas plantillas FreeMarker.
– Un Script controlador opcional.
– Archivo de Configuración.
– Archivo de propiedades de Idioma.

• Todas las URL de los web scripts deben comenzar

por /alfresco/service/ , el resto es libre aunque
con la restricción de que debe ser único.
 Construcción de una API con Alfresco Web Scripts

• El descriptor es un documento .xml que se debe

almacenar en una de las carpetas de web scripts,
o en cualquiera de sus subcarpetas.
• La nomenclatura es importante. Los Web Scripts
emplean convenciones sobre la configuración de
su definición para reducir la cantidad de escritura
requerida. La terminación .desc.xml indica a
Alfresco que se trata de un documento de
descripción de Web Scripts. El nombre completo
de la carpeta y el archivo definen:
– Un paquete.
– Un id de servicio.
– Un vinculo al método HTTP.
 Construcción de una API con Alfresco Web Scripts

Ejemplo de un Archivo Descriptor

 Construcción de una API con Alfresco Web Scripts

• shortname es un nombre legible para el web script. El

elemento description es opcional y sirve para documentar
la funcionalidad.
• Podemos tener uno o varios elementos url. Estos elemento
definen las plantillas URL a las cuales el web script esta
vinculado.
• El elemento format especifica como es declarado el tipo de
la respuesta en la url. Los valores validos son:
– argument: El tipo de contenido sera declarado con un
argumento llamado format en la url.
(/buscar?q=tutorial&format=atom ) .
– extension: El tipo de argumento sera declarado usando la
extensión de la url. Por ejemplo. (/buscar.atom?q=tutorial).
– any: Cualquiera de las dos formas anteriores esta permitida.
Este será el valor por defecto si el elemento no es especificado.
 Construcción de una API con Alfresco Web Scripts

• El elemento opcional authentication indica los

requerimientos a nivel de autenticación. Los
valores validos son:
– none: No es requerida ningún tipo de autenticación.
Este es el valor por defecto si el elemento no es
especificado.
– guest: Al menos es requerido autenticarse como
invitado para acceder al web script.
– user: Al menos es requerido autenticarse como un
usuario para acceder al web script.
– admin: Es necesario autenticarse como admin para
acceder al web script.
 Construcción de una API con Alfresco Web Scripts

• El elemento opcional transaction indica el

nivel requerido de transacción. Los valores
validos son:
– none: Indica que no se necesita ninguna declarar
una transacción.
– required:Indica que se necesita una transacción
para la ejecución del web script. Se puede heredar
una transacción que ya este abierta.
– requiresnew: Indica que se requiere una nueva
transacción.
 Construcción de una API con Alfresco Web Scripts

Plantillas URL
– Una plantilla URL es simplemente un url que
contiene tokens que pueden ser sustituidos con
valores reales. La sintaxis de una plantilla URL es
simple y sencilla. Ejemplos comunes de plantillas
URL incluyen:
 Construcción de una API con Alfresco Web Scripts

Formatos de respuesta
– Un web script soporta intrínsicamente un formato de
respuesta por defecto. Un formato de respuesta es un
nombre corto registrado (atom) que identifica un
tipo/subtipo MIME (application/atom+xml).
– No obstante es posible para cualquier web script
soportar múltiples tipos de respuesta. Cuando este es
el caso es necesario determinar que formato se
escoge cuando un web script es invocado. Esto se
consigue codificando el formato en la URL ya sea
como un argumento (format) o como una extensión.
Cuando no se especifica de ninguna de estas formas
siempre se escoge el formato por defecto.
 Construcción de una API con Alfresco Web Scripts

Formatos de respuesta
 Construcción de una API con Alfresco Web Scripts

• Script Controlador
– Un web script puede opcionalmente ejecutar
código JavaScript en algunas invocaciones de su
respectiva URL. El código JavaScript puede realizar
consultas o actualizaciones contra el repositorio.
Además, el código JavaScript puede construir un
modelo de datos que se pasa a la plantilla de
respuesta adecuada para su posterior prestación.
 Construcción de una API con Alfresco Web Scripts

• Script Controlador

Convención de Nombres
 Construcción de una API con Alfresco Web Scripts

• Script Controlador
– La API JavaScript de Alfresco es completamente
accesible desde los web scripts.
– Sin embargo, hay algunas diferencias en cuanto a
la disponibilidad de los objetos raíz: los objetos
document, space y script ~~ no estarán
disponibles y los objetos ~~companyhome, person
y userhome solo estará disponible si se esta
autenticado.
 Construcción de una API con Alfresco Web Scripts
• Objetos raíz adicionales:
– argsM: Una matriz asociativa de cualquier parámetro de URL (donde
cada llave es un nombre de parámetro y cada valor es una matriz que
contiene los valores de los parámetros, aunque sólo uno sea
suministrado) - complementa al objeto raíz args. Véase el ejemplo.
(disponible a partir de V2.1 Enterprise).
– url: Proporciona acceso a la url (o partes de la url) que desencadeno el
web script.
– formdata: Proporciona acceso a peticiones multipart/form-data
permitiendo la subida de archivos por medio de web scripts.
(Disponible a partir de V2.1 Enterprise).
– model: Un array asociativo vacío que puede ser rellenado por el
JavaScript. Los valores almacenado aquí estarán disponibles como
objetos raíz para las plantillas de respuesta.
– roothome: El nodo raíz del Repositorio.
– guest: Un booleano que indica si el web script se esta ejecutando
como "Guest"
– server: Un array de meta-datos que describen las propiedades del
servidor del Repositorio que aloja el web script.
 Construcción de una API con Alfresco Web Scripts

• Plantilla de Respuesta
– La fase final de un web script es presentar una
respuesta para la petición HTTP. Se pueden
proporcionar multitud de formatos de respuesta.
Las respuestas son presentadas usando plantillas
FreeMarker.

Convención de Nombres
 Construcción de una API con Alfresco Web Scripts

• Plantilla de Respuesta
– La API de Plantillas de Alfresco es completamente
accesible desde los web scripts. Sin embargo, hay
algunas diferencias en cuanto a la disponibilidad
de los objetos raíz: los objetos document, space y
template no estarán disponibles y los objetos
companyhome, person y userhome solo estará
disponible si se esta autenticado.
 Construcción de una API con Alfresco Web Scripts

• Objetos raíz adicionales:

– argsM: Una matriz asociativa de cualquier parámetro de URL
(donde cada llave es un nombre de parámetro y cada valor es
una matriz que contiene los valores de los parámetros, aunque
sólo uno sea suministrado) - complementa al objeto raíz args.
Véase el ejemplo. (disponible a partir de V2.1 Enterprise).
– guest: Un booleano que indica si el web script se esta
ejecutando como "Guest".
– date: Una representación en formato fecha del dia y la hora de
la llamada al web script.
– server: Un array de meta-datos que describen las propiedades
del servidor del Repositorio que aloja el web script.
– roothome: El nodo raíz del Repositorio.
– webscript: Un array de meta-datos que describen las
propiedades del web script.
– url: Proporciona acceso a la url (o parts de la Url) que
desencadeno el web script.
 Construcción de una API con Alfresco Web Scripts

• Existen también algunos métodos adicionales a los que

tienen acceso las plantillas:
– absurl(url): Devuelve una representación URL absoluta de la url
pasada por parametro. Es útil cuando se están presentando
enlaces sin ATOM(o un formato similar)
– xmldate(date): Devuelve como resultado una representación
formateado según el estandar ISO8601 de la fecha pasada por
parámetro. Es útil cuando se representen fechas con XML.
– scripturl(queryString): Devuelve la url que referencia al web
script. La cadena queryString pasada por parametro es añadida
a la url. Argumentos del sistema como format son añadidos
automáticamente también. Este método es particularmente útil
para aislarse del entorno en el que está ejecutando el web
script. En algunos entornos de ejecución la url puede estar
codificada.
– clienturlfunction(funcName): Genera una función JavaScript en
el cliente que puede generar un URL de vuelta al web script.
 Construcción de una API con Alfresco Web Scripts

Respuestas en Múltiples Formatos

– Las respuestas en múltiples formatos son posibles
gracias a la creación de archivos de plantillas
adicionales siguiendo la convención de nombres
que se vieron antes.

Ejemplos para Solicitud de Formato

 Construcción de una API con Alfresco Web Scripts

Servicios a ser desarrollados en los Ejercicios

 Alfresco para Desarrolladores

Conclusiones