SharePoint 2013’s Call HTTP Web Service Workflow Action–Part 1

Part – 1 - Introduction

SharePoint 2013 introduces some very cool and powerful features with the addition of Workflow Manager. In this series of blog posts, I will cover one of my favorite SharePoint 2013 workflow activities, Call HTTP Web Service.

The Call HTTP Web Service is a new activity that is provided with SharePoint 2013 and Workflow Manager. This activity allows you to call a web service from within your workflow. This provides a workflow author with the functionality to consume data from an external web service. A workflow author could also use the action to query other SharePoint objects (Site,Web,List,etc..) by using SharePoint’s REST interface.

This series of blog posts will use a simple real world scenario to show the power of the Call HTTP Web Service activity. The scenario I will demonstrate is querying a list for items that meet certain criteria from within the workflow. Once I receive the items from the call, I will perform some action on the data.

Let’s say I have an Issues list in my SharePoint 2013 site. This list is used as a ticketing system for users to enter any issues they are having. When the issue is created, a person will be assigned to work the ticket and provide a resolution to the issue. The person that is assigned the ticket can set the status of the ticket to “On Hold”. We don’t want the assigned to person to forget about their “On Hold” tickets. We will create a SharePoint 2013 Site Workflow that will execute weekly and get all tickets that have their status set to “On Hold”. We will then iterate through the “On Hold” tickets and email the assigned to person to remind them about their tickets.

The screenshot below shows the list’s fields and their types:

This list was created from the out of the box Issue Tracking list template.

Next we will open up the SharePoint 2013 site in SharePoint 2013 Designer and create a new SharePoint 2013 Site Workflow. When the workflow editor opens, we will rename the first stage to “Get Issues On Hold” and add the Call HTTP Web Service action.

In the screenshot above, you can see that there are a few parameters for this action. The parameters we are interested in are listed and described in the steps below:

1. This –  the “this” parameter allows you to enter the URL for the web service. When you click on the “this” parameter, the following dialog box pops up:

In the text box, we need to enter the URL for our list’s REST endpoint. The URL we will enter is below:

http://lab13.codygros.com/_api... eq 'On Hold'&$orderby=AssignedTo/Name

In this first post I won’t go too deep into the syntax of the URL because this will be explained in the second blog post. For now, I will give the high level details:

http://lab13.codygros.com

This base part of the URL is the SharePoint site where my list Issue list resides.

/_api

The entry point for accessing SharePoint 2013 REST endpoints is the “/_api” path. You append this behind the site’s URL.

/lists

This tells SharePoint what type of object you would like to query. In this example, we want to get our Issues list.

/getByTitle(‘Tickets’)

This tells SharePoint to give me a specific list with the name of “Tickets” (The name of the Issues list).

/items

This tells SharePoint to return the items from the Tickets list.

The rest of the URL provides operations such as filtering, selecting specific fields, ordering and expanding. We will cover these in detail in the next post. For now, I’m telling SharePoint to give me all items from the Tickets list that have their Status field set to “On Hold”.

I will put the above URL in the dialog box as show below:

In this example, we will leave the HTTP Method to HTTP Get because we are just retrieving data from the service.

2. Response – The response parameter is used to store the data that is returned from the web service call. If you click on this parameter, you will be prompted to create a new workflow variable of type “Dictionary”. This is a new variable type in SharePoint 2013 workflows that allows you to store key value pairs.

Our web service call will return a JSON object. Don’t worry at this point if you are not familiar with JSON, we will cover it in the next post. For this example, I will set it to a variable named jsonResponse of type dictionary.

  For this example, those are the only two parameters we need to set on the Call HTTP Web Service Action. When accessing a SharePoint 2013 REST endpoint, we are required to set the HTTP Request header’s accept property. To set this property, we have to perform the following steps:

1. Above the previous Call HTTP Web Service action we added to our workflow, we need to add the Build Dictionary action. This is another new action in SharePoint 2013 that allows you to build a dictionary object.

2. Click on the “this” parameter on the action and add the values as shown below:

We are creating a property in our dictionary object named “accept” and giving it the value of “application/json;odata=verbose”.

3. Now we have our dictionary object created, we will set the Call HTTP Web Service action’s HTTP header property to our dictionary object. To do this, right click on the Call HTTP Web Service action and click Properties.

In the properties box, set the RequestHeaders property to the dictionary variable we created in the previous step.

It is important to set the HTTP Request Headers property. If this property is not set, the web service call will not work.

This wraps up the first blog post in this series. Our Call HTTP Web Service action is set up to query our issues list. In part 2 of this blog series, we will dive into the web service response. Looking to further expand your knowledge on Sharepoint? Check out this blog on expediting ROI.

Information and material in our blog posts are provided "as is" with no warranties either expressed or implied. Each post is an individual expression of our Sparkies. Should you identify any such content that is harmful, malicious, sensitive or unnecessary, please contact  marketing@sparkhound.com