Fiddler es una herramienta bastante recomendada para ejecutar y probar las distintas operaciones REST que vayamos a utilizar desde un WorkFlow en SharePoint Designer 2013. Esto se debe a que la depuración y revisión rápida de lo que está sucediendo desde el WorkFlow y los pasos definidos en Designer, es realmente una tarea que consume demasiado tiempo y es difÃcil para el desarrollador que requiere realizar sus tareas con productividad. Por tal razón necesitamos descargar e instalar Fiddler (http://www.telerik.com/download/fiddler). Es recomendable, si estamos trabajando desde Windows 8.1, descargar la versión especÃfica de la herramienta para este sistema operativo, tal como lo aclaran en la página. A continuación veremos los pasos a seguir para ejecutar una operación REST de SharePoint 2013 desde Fiddler:
Habiendo instalado Fiddler, ejecutamos la herramienta.
Cuando cargue Fiddler utilizamos F12 para iniciar la captura del tráfico.
Luego de ejecutar el servicio en Fiddler se puede ver un mensaje en color amarillo, sobre el cual se debe hacer clic para decodificar las respuestas que vienen desde el sitio de SharePoint. De inmediato se podrá ver un mensaje que nos indica que el llamado no se puede ejecutar por falta de permisos: HTTP/1.1 403 Forbidden.
Es importante en el menú Tools de Fiddler hacer clic en Fiddler Options, seleccionar el TAB HTTPS y seleccionar las opciones que permiten capturar los llamados HTTPS, debido a que SharePoint Online 2013 hace las peticiones utilizando ese protocolo. Activamos las siguientes opciones como muestra la siguiente figura.
Como ya se tiene configurada la herramienta para escuchar las peticiones HTTPS, debemos abrir una ventana del navegador y ahà iniciar una sesión en el sitio de SharePoint Online 2013. En la ventana que solicita nuestras credenciales, ingresarlas, seleccionar la opción que permite mantener la sesión iniciada, y al finalizar la redirección al sitio, nuevamente regresamos a Fiddler para buscar las cookies que requerimos para poder hacer los llamados REST. Esto se puede buscar en Fiddler en la ventana que está escuchando todas las solicitudes realizadas y luego encontrar el valor de la cabecera Cookie que se envÃan al sitio de SharePoint Online 2013 durante las peticiones. La siguiente figura muestra lo anterior.
Seleccionamos el valor FedAuth, y lo copiamos para luego utilizarlo.
En Fiddler nuevamente regresamos al TAB Composer y agregamos la cabecera para realizar nuevamente la solicitud al servicio REST que habÃamos intentado antes.
Luego se puede observar la ejecución de la operación approve, la cual es la que permite realizar la APROBACIÓN del documento en cuestión, adicionando un mensaje cualquiera, tal como si se aprobara el documento desde la interfaz Web en el sitio de SharePoint.
NOTA: En caso que la biblioteca haya sido configurada para requerir CheckIn y CheckOut de los documentos, en el WorkFlow deberÃamos ejecutar la acción que desproteja el documento para poder ejecutar acciones como la de APROBACIÓN y todo lo que requiera cambios sobre el elemento. Para este ejemplo, asumimos que no es necesario desproteger el documento.
En Fiddler si ejecutamos el llamado REST ya descrito, vamos a obtener un Error 403 Forbidden, como se muestra en la figura.
El error es debido a la ausencia de un valor más en la cabecera de la solicitud. Ese valor es el del parámetro X-RequestDigest. Para conseguir dicho valor, es necesario componer una llamada a un servicio REST con la operación POST que retorna el valor de FormDigestValue, valor que se usará en la cabecera de solicitudes con la variable X-RequestDigest.
Teniendo el valor de X-RequestDigest es momento de volver a ejecutar el servicio REST que nos permitirá APROBAR el documento: https://intranet/_api/web/GetFileByServerRelativeUrl('/documentos/midocumento.docx')/approve(comment='El documento ha sido aprobado')
La llamada anterior desde Fiddler deberá retornar un resultado 200 OK. Y si se revisa el documento en el sitio de SharePoint este deberá aparecer como APROBADO con el mensaje "El documento ha sido aprobado".
Crear y configurar un WorkFlow en SharePoint Designer 2013
Luego de probar y validar el correcto funcionamiento de nuestras solicitudes REST desde Fiddler, es el momento de crear el WorkFlow en SharePoint Designer, agregar la acción que permite invocar el servicio REST y tenemos una alta probabilidad que todo funcione de manera correcta. La acción Registrar en lista de historial es una buena forma de registrar valores que nos permiten ir validando que el WorkFlow se está ejecutando de manera adecuada asà como los servicios REST invocados.
Lo primero es que debemos contar con permisos necesarios para realizar los siguientes pasos, por ejemplo ser Propietarios del sitio.
Teniendo los permisos suficientes, procedemos a abrir SharePoint Designer 2013 y cargamos el sitio en el cual vamos a crear el WorkFlow.
De inmediato vemos que se cuenta con varias opciones para crear WorkFlows: WorkFlow de lista, reutilizables y de sitio. Para el propósito de este ejemplo, usaremos el WorkFlow de Lista y seleccionamos la lista o biblioteca de documentos sobre la que queremos que se ejecute el WorkFlow.
Luego se abrirá un Wizard que nos permitirá configurar las opciones iniciales del WorkFlow. Por ejemplo asignarle un nombre, una descripción, y lo más importante escoger el tipo de Plataforma, en este caso y para tener la opción de invocar servicios REST desde el WorkFlow, debemos seleccionar SharePoint 2013 WorkFlow.
Al hacer clic en el botón OK, SharePoint Designer 2013 despliega una ventana que permitirá crear y configurar los distintos pasos del WorkFlow.
A continuación asignamos un nombre a la fase, por ejemplo Aprobación. En la sección Transition to stage hacemos clic y agregamos la acción Ir a una fase y seleccionamos el valor Final del flujo de trabajo. En este caso es un ejemplo simple que no requiere de varios pasos, pero podemos agregar todos los pasos o fases necesarias para nuestro proceso.
Finalizamos la configuración del diccionario haciendo clic en el botón OK. Por defecto SharePoint Designer crea la variable diccionario, pero en la acción se puede crear una nueva si asà se desea.
Luego hacemos clic derecho sobre la acción Llamar al servicio web HTTP que ya habÃamos agregado y seleccionamos la opción Propiedades. En la ventana que se abre ubicamos la opción RequestHeaders y ahà asignamos como valor el diccionario que acabamos de configurar en pasos anteriores.
Con lo anterior el servicio podrá ejecutarse correctamente y es momento de obtener el valor de FormDigestValue retornado por el servicio. Para esto creamos una variable local con el nombre FormDigestValue o el que se desee, de tipo Diccionario.
Con el valor de FormDigestValue es posible agregar la acción que permitirá hacer la llamada al servicio REST que nos permitirá APROBAR el documento.
Luego de haber seguido los pasos anteriores debemos tener el WorkFlow similar a como se ve en la siguiente figura.
Para finalizar la configuración del WorkFlow hacemos clic en su nombre, Aprobación REST, desmarcamos el valor Automatically update the workflow status to the current stage name y seleccionamos la opción Start workflow automatically when an Ãtem is created.
Finalmente hacemos clic en el botón Guardar y Publicar de SharePoint Designer 2013 para poder probar el WorkFlow en la biblioteca de documentos.
Para probar el WorkFlow vamos al sitio de SharePoint, ubicamos la biblioteca a la cual asociamos el WorkFlow que se acaba de crear y configurar, damos de alta un documento a la biblioteca y el WorkFlow deberá iniciar y terminar satisfactoriamente. Luego de esto al revisar el historial de versiones del documento o las opciones de Aprobación, debemos encontrar que ha sido aprobado con el mensaje que hemos usado en este ejemplo.
En conclusión hemos podido evidenciar que la inclusión y uso de REST dentro de SharePoint, es una gran ventaja para que los desarrolladores puedan consumir y enviar información a los sitios en SharePoint desde las aplicaciones cliente que implementan, y que se encuentra disponible en las versiones Online y Onpremise de la plataforma. Debido al uso de REST los desarrolladores de gran variedad de plataformas podrán construir estas aplicaciones que se comunica con SharePoint: JAVA, PHP, Android, IOs, entre otras.
Finalmente vemos que la inclusión de la acción que permite hacer llamado a los servicios REST de SharePoint desde los pasos de un WorkFlow, es una capacidad realmente potente e importante para que el resultado final de los WorkFlows construidos con Designer realmente agreguen valor a las organizaciones que muchas veces requieren integrar estos procesos con información adicional, y no estar atados únicamente a los Ãtems de una lista y/o biblioteca.