Tuesday, September 8, 2015

How to call SharePoint REST Web Services from SharePoint Designer 2013 and Fiddler?

What?

SharePoint 2013 introduced a new action in SharePoint Designer 2013 workflows to call a http web service called "Call HTTP Web Service".

There are thousand other blog posts explaining how to use that action but in this post I am going to focus on and detail how to use GET and POST http methods with REST based native SharePoint 2013 web services.

Why?

SharePoint 2013 (and previous versions) uses a client side “token” to validate posts back to SharePoint to prevent attacks where the user might be tricked into posting data back to the server. This token is known by many names; form digest ormessage digest or request digest. The token is unique to a user and a site and is only valid for a (configurable) limited time.

Calling a SharePoint 2013 REST POST http method therefore requires adding the Request Digest token to the request header of the request as the “X-RequestDigest” header.

How?

The first step to test out the queries is to use CAML Designer 2013 and Fiddler.



CAML Designer 2013 provides the ability to build REST urls with selected fields,  filters and order by.conditions.



Calling a SharePoint REST web service using a GET http method is straight forward.

Fire up Fiddler and go to composer > options
Make sure that the check box "Automatically Authenticate" is checked.



Click on the tab "Parsed" and choose "GET" as the http method.
Provide the full REST url. You can use CAML Designer to build this. (ex: http://site/_api/web/Lists/getByTitle('Target%20List')/Items)

Ensure that the below headers are added to the request headers section:

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



Click the Execute button and you will see the results.



There are so many nice posts in the internet explaining how to call an HTTP GET REST Web Service using a SharePoint Designer workflow and parse the results.

Updating a item using POST that does not belong to a list in the web in which the workflow runs however is tricky as it requires you to add the Request Digest token to your request.

POST using Fiddler:

Any POST operation requires the X-RequestDigest token.

As described on this page on MSDN, you can retrieve this value by making a POST request with an empty body to http://site/_api/contextinfo and extracting the value of the "d:FormDigestValue" node in the XML that the contextinfo endpoint returns.

Open Fiddler and go to composer.
Specify POST as the http method and http://{site}/_api/contextinfo as the url.
Ensure the below headers are added to the request header:

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



You will see the below results when you execute.

The below procedure explains how to update an item.

Copy the X-RequestDigest token (highlighted in yellow)



Open Fiddler and go to composer.
Specify POST as the http method and the REST query to retrieve the item to update.

Ensure that the below headers are added to the request header:

ACCEPT: application/json;odata=verbose
Content-Type: application/json;odata=verbose
X-RequestDigest: (In this format: 0x269CE93D2C4929E37FDFABE3994611EB74791A66681DC23CBC04CEDDAF85C99B87D2B2F82B5F75F9E788A15986F04E37C0A7739F4371DB7527969FEBB1FA1AAB,08 Sep 2015 01:40:18 -0000)
X-HTTP-Method: MERGE
IF-MATCH: *
Content-Length: 91

Please note that the below headers are important to perform updates:
X-HTTP-Method: MERGE
IF-MATCH: *

Build the request body to update the item:

For example the following will update a column named Booked Leave with value 23 in a list item:
{ '__metadata': { 'type': 'SP.Data.Target_x0020_ListListItem' }, 'Booked_x0020_Leave': 23 }

If you are not sure about how to build the response body, please refer to this awesome post by Fabian



Hit execute and you should see "HTTP/1.1 204 No Content" in the response header for a successful update.

If the response header contains "Forbidden", it can mean that the request digest token is invalid.

Post using SharePoint Designer 2013:

The request digest token is unique to a user and a site and is only valid for a (configurable) limited time.
It therefore has to be updated every time before a POST method is called.

This wonderful post by Alaxandre explains how to update a list item in a list that resides in the same web as the item on which the workflow is triggered using SPD 2013.

For updating items that reside in a list that belongs to a different site collection / web,follow the below process:

Build a dictionary with the following headers:
ACCEPT: application/json;odata=verbose
Content-Type: application/json;odata=verbose
Authorization: Leave empty. Do not specify ""



Call the action "Call HTTP Web Service" with the url: http://{site url}/_api/contextinfo and specify "POST" as the http method. Make sure that you set the above dictionary as the request header.

Call the action "Get an item from a Dictionary" with "d/GetContextWebInformation/FormDigestValue" as the value for "item by name or path" from the response of the above action and output to a string variable.

Use the above request token with the POST request header to update the list item.

Your request header dictionary should look like the below:



Run the workflow and you should see "No Content" in the response header for a successful update.

If the response header contains "Forbidden", it can mean that the request digest token is invalid.

Hope that this helps.

1 comment:

  1. Expected and valid points are included in you blog.. I really liked and I got some clear ideas for improve my thoughts from well defined content... keep updating more for us... thanks for shared useful blog..
    SEO Company in Chennai

    ReplyDelete