jueves, 6 de marzo de 2014

SP Designer 2013: Cómo usar la acción de "Call HTTP web service" para obtener los ítems de una lista de SharePoint

Sin duda ya casi todos sabréis que una de las novedades de SharePoint Designer 2013 en cuanto a la generación de workflows es que ahora incluye por defecto la acción "Call HTTP web service".
Lo que quizás algunos no sabréis es cómo utilizar correctamente esta acción, ya que no es tan trivial como pudiera parecer.

Voy a centrarme en un ejemplo de cómo atacar a las propias listas de SharePoint, para obtener un listado completo de ítems de una lista. Recordad que otras de las novedades de los flujos en SharePoint 2013 es que podemos crear variables de tipo array ("Dictionary") de datos, y usar bucles (loops). Todo junto, nos ofrece una serie de posibilidades que para emularlas en 2010 hubiéramos tenido que tirar de desarrollos a medida, soluciones de terceros o apaños rocambolescos.

Para obtener de forma estándar (sin desarrollos a medida) el listado de ítems de cualquier lista o biblioteca que queramos de nuestro SharePoint en SharePoint Designer, tendremos que hacerlo haciendo uso de los Web Services GET que SharePoint pone a servicio para obtener datos de listas/bibliotecas.

 Tal y como podemos ver en las páginas de MSDN respecto al REST service, las llamadas a los Web Services para obtener datos de listas/bibliotecas son las siguientes:
 
Description
URL endpoint
HTTP method
Retrieves the title of a list
web/title
GET
Retrieves all lists on a site
lists
GET
Retrieves a single 'list's metadata
lists/getbytitle('listname')
GET
Retrieves items within a list
lists/getbytitle('listname')/items
GET
Retrieves a specific property of a document. (In this case, the document title.)
lists/getbytitle('listname')?select=Title
GET

Así pues, nuestro Web Service debe tener una estructura como la siguiente (recomiendo probarlo previamente en el navegador, para comprobar sus resultados antes de trabajar con esta cadena de conexión en SharePoint Designer):

https://sitecollection/site/_api/web/lists/GetByTitle('listname')/items

Otro punto importante a tener en cuenta es que en la api REST de SharePoint 2013, las llamadas han de tener formato JSON, y para ello, tendremos que añadir información en las cabeceras http (http headers) de la llamada REST, concretamente tendremos que construir la siguiente cabecera:

Accept : application/json;odata=verbose
Content-Type : application/json;odata=verbose

Para hacerlo, primero tendremos que crear una variable en SharePoint Designer de tipo Dictionary (Local Variables - Add).


El siguiente paso es añadir a nuestro flujo una acción del tipo "Build Dictionary" (en "Core Actions"). En ella añadiremos los siguientes valores:

  • Name
    • Content-Type
  • Type
    • String
  • Value
    • application/json;odata=verbose
y también:
  • Name
    • Accept
  • Type
    • String
  • Value
    • application/json;odata=verbose
Como output, indicaremos la variable de tipo Dictionary que acabamos de crear.


Con la cabecera http construida, ya podremos invocar el Web Service de forma exitosa. Para ello añadiremos la acción Call HTTP Web Service (en "Core Actions") a nuestro flujo, con los siguientes parámetros:
  • this: Pulsar y añadir la cadena de conexión al WS, seleccionando el método HTTP GET
  • request: Dejar en blanco
  • response: Añadir aquí una nueva variable de tipo Dictionary, donde se almacenará el XML retornado en formato JSON.
  • responseHeaders: Dejar en blanco
  • variable: Nueva variable de tipo String que informará de si la operación se ha ejecutado correctamente o no (se aconseja justo después de la acción Call HTT Web Service, usar la "Log to History List" y mostrar esta variable, para comprobar si la llamada se ha realizado correctamente o no)

Hay que tener en cuenta para qué sirve cada método y por qué nosotros, en este caso, especificamos el HTTP GET.
  • HTTP GET - Para obtener información.
  • HTTP PUT - Para crear nueva información.
  • HTTP POST - Para editar información ya existente.
  • HTTP DELETE - Para borrar información ya existente.
Ahora tendremos que introducir en nuestra llamada, la cabecera HTTP que preparamos previamente. Para ello, desplegad el menú de opciones de la acción Call HTTP Web Service, y seleccionad "Properties..."
 
En el campo "RequestHeaders" es donde debemos indicar el nombre de la variable de tipo "Dictionary" que preparamos previamente (pulsad OK para guardar los cambios).


 Pues ahora sí, nuestra acción de llamada a servicio web HTTP debería funcionar correctamente.

¿Cómo podemos explotar la información retornada en la variable del campo "response"? Pues mediante la acción "Get an Item from a Dictionary" (Core Actions)

Hay que tener en cuenta que el formato JSON de los REST Services que retornan elementos de listas de SharePoint, tienen un formato del tipo:


Y por tanto, para referirnos a ellos desde una variable de tipo Dictionary deberemos hacerlo mediante "d/results".

En la acción de "Get an Item from a Dictionary", si queremos obtener todo el conjunto de resultados (todos los ítems), tendremos que especificar los siguientes valores:
  • ítem by name or path: "d/results". Que, como hemos visto es el formato de esquema XML que retorna el JSON de los REST Services de SharePoint.
  • dictionary: Variable de tipo Dictionary que pusimos en el parámetro "response" de la acción "Call HTTP Web Service"
  • ítem: Una nueva variable de tipo Dictionary, donde almacenaremos el conjunto de valores retornado.

Aquí comentar que también podríamos acceder a un ítem concreto (con todos sus metadatos) si en lugar de "d/results" especificamos "d/results(0)", donde (0) es el índice del elemento al que queremos acceder, siendo (0) el primer elemento retornado, (1) el segundo, etc. Puesto que seguiría retornando un conjunto de elementos, el Output debería ser una variable de tipo Dictionary.

Por último, también podríamos acceder a un metadato/propiedad específica de un elemento concreto, utilizando en este caso "d/results(0)/Title", donde "Title" es el nombre del metadato/propiedad que queremos obtener. En este caso, el output será una variable de tipo string, number, boolean, Date/Time... en función del metadato en cuestión.

Hasta este punto, nuestro flujo en SharePoint Designer, debería tener un formato similar al de la siguiente imagen:

 
Así pues, ya hemos visto cómo atacar a una lista de SharePoint mediante una Call HTTP Web Service action de SharePoint Designer 2013 y explotar sus resultados.

De momento lo dejamos aquí, pero en un próximo post (SP Designer 2013: Bucle para recorrer todos los ítems de una lista), veremos cómo podemos aprovechar el trabajo realizado hasta ahora, para, por ejemplo, recorrer ítem por ítem una lista de SharePoint y efectuar cambios en todos sus elementos (loop para modificar todos los ítems de una lista).

Hasta entonces, ¡Un saludo!

No hay comentarios: