The Fundamental SharePoint Workflow HTTP Web Service Call Overview

SharePoint Developer 2013’s built-in workflow service can appear very limited.  Thankfully there is an action contained within the Workflow designer that expands the capabilities of the workflow. This step is the HTTP web service call.

This article is focusing primarily on the ability to post (using the POST verb) items to a list or document library using the HTTP Web Service action and not simply retrieving (the GET verb) data. I wanted to write this post because I could not find a single article that had all of the pertinent information in one place. I was going to multiple different places to find this. So hopefully, this will help you as it has helped me.


One of the biggest differences between performing a POST operation in lieu of a GET operation is the need for having the request digest value. The request digest is a value that is passed to the browser during the POST operation to ensure that the browser is who it is claiming to be. It’s another security feature to prevent the hijacking of a REST operation. Therefore, the first step to achieving a successful POST call in a workflow is the ability to obtain the Request Digest value. This step presents two challenges – the first being that the value is retrieved during another REST call AND the value changes over time. This means that there must be a separate call conducted first each time to retrieve the updated Request Digest value. Here is how I did it:

ESTABLISH DICTIONARY

  • I created a new step within my workflow title ‘Get Security Context’
  • I then created a new dictionary variable title ‘contextHeader’ and placed these three (required) values:

Name: accept Type: String Value: application/json;odata=verbose

Name: content-type Type: String Value: application/json;odata=verbose

Name: content-length Type: String Value: 255

HTTP WEB SERVICE POST CALL TO _contextinfo

  • I then created a POST call by adding the Call HTTP Web Service step. This is the step where we obtain the request digest value.

The URL that you want to use is (this is for SP Online) https://<yourSPtenant>.sharepoint.com/_api/contextinfo – You can also use other site collections as well. For example: https://<yourSPtenant>.sharepoint.com/sites/<siteCollectionName>/_api/contextinfo

You then want to set the HTTP method to ‘POST’

  • Next, we need to edit the properties of the HTTP call web service action that we placed in our workflow. To do this we need to hover our cursor over the action and right click on it (or you can select the drop down on the far right hand side.

  • In the next step, we want to add our contextHeader variable to the request header options of the HTTP call:

  • The Final part of this (if you chose to change it) is to update the response content and response status code to different variables. You don’t have to change them, however, you will need to know which variable your response content is stored in.

  • Click ‘ok’ when finished. Now, we are able to move onto the next step.

RETRIEVE DIGEST VALUE

  • The next part is to create another step, which I call ‘Get token values and build headers’:

  • Now we need to get the request digest value from the returned header object. To do this, we need to use the ‘Get Item from a Dictionary’ action in our workflow.

  • Click on ‘item by name or path.’ It allows you to either build a string or select a function. We want to build a string (by clicking the ellipsis). The value needs to be pulled from the object. The proper path needs to be added: d/GetContextWebInformation/FormDigestValue

  • Now, make sure that the ‘from’ part of the action is set to the variable that contains the Response Content from the previous HTTP Web call. For this example, that variable is called ‘contentResponse’:

  • Finally, we need to store the information into a variable. I labeled this one ‘digestValue’ because it will be easier for me to remember what it is later.

BUILD LIST DICTIONARIES

The first dictionary that needs to be built is the request headers.

  • For this HTTP call, we need three headers: accept, content type, and x-requestdigest. They can then be output to a variable with a name of your choice. For my workflow, I named the output variable JSONrequestHeaders. Here is how the dictionary is set up:

Name: accept Type: String Value: application/json;odata=verbose
Name: content-type Type: String Value: application/json;odata=verbose
Name: X-RequestDigest Type: String Value: variable:digestValue

  • The next dictionary is for the metadata. The only value in this dictionary is the type. Now, the type is the ListItemEntityTypeFullName value found in a simple REST call to the list. It is then stored in a variable that I called restMetaData. For this example, the list type is: SP.Data.TestListListItem

  • The final dictionary is the rest parameters dictionary (I stored this in a variable called ‘restParams’). This is the body that is passed to the list that contains the information of the item we are trying to add. For this simple example, we are only trying to create an item with the title ‘SP Test.’ This dictionary is created with the following:

Name: __metadata Type: Dictionary Value: variable: restMetaData
Name: Title Type: String Value: SP Test
There are 2 underscores in front of metadata.

CREATE FINAL HTTP WEB SERVICE CALL

We now get to build the final HTTP Web Service call and test our hard work.

  • Add the Call HTTP Web Service to the end of our step.
  • Where the action says ‘Call this’ click on ‘this’
  • Now we want to add our url and the HTTP method. For this demo the url is https://<tenant>.sharepoint.com/sites/onboarding/_api/web/lists/getbytitle(‘testList’)/items and the method is ‘Post’

  • Just like the previous call, we want to right click on the action and select ‘properties’
  • For the properties, we want to place the followingRequestHeaders -> Variable: JSONrequestHeaders (or whatever you named it)
    • RequestContent -> Variable: restParams (or whatever you named it)
    • ResponseContent -> Variable:Response
    • ResponseHeaders ->
    • Response Status Code -> I leave this as the SP generated variable

 

  • The final call action will be:

OUTCOME

Now run your workflow and see the new list item appear:

One thing I do recommend is that you log each step to the workflow history so you can troubleshoot when something inevitably does not go as planned. I have tons of logs to my history in each workflow I create so that if there is a breakdown, I know where to look first.

Hope this helps!

Need help with SharePoint? Feel free to contact me.

Have a bigger project? Check out my company, UDig, LLC.