Sunday, September 14, 2014

A Guide to Calling SharePoint Web Services in SharePoint Designer 2013 Workflows

There was a time in my life when making web service calls was like asking me to speak French (Non, je ne sais pas comment appeler un service Web SharePoint). Thankfully, third-party workflow products make my life easy with handy-dandy wizards. Calling a web service from SharePoint Designer doesn't give you the luxury of the wizards. Plus, there's the added difficulty of having to deal with JSON which might as well be Sanskrit to those of us who don't write compiled code. In this post, I'm going to assuage your web service fears and concerns. So sit back relax and strap on your seat belt because this is a guide to calling a SharePoint web service in SharePoint Designer 2013 workflows.

First of all, here's a little context as to how I arrived at this post. All of my workflows that use web services to date have been built on SharePoint 2010. Workflows I've built in 2013 have been 2010 workflows and as such are not able to call web services.

Like many people, I was ecstatic when I saw the demo where a SharePoint workflow gets eBay's daily deal. However when it comes time to develop a workflow that interacts with SharePoint data, it's nothing like the demo (shocker!). And let me also say this, in the two years since the debut of this video, there is surprisingly little about how to make this happen using SharePoint data.

But back to the problem. In my 2013 workflow, I tried calling http://site/_vti_bin/lists.asmx and was getting nothing I could work with. My tried and true approach left me spinning my wheels. I cracked open Fiddler and started composing a request there, adjusting the request headers based on this blog and that but still no luck. Long story short, I was doing it wrong; when working with SharePoint web services in 2013 SPD workflows, you need to use REST endpoints.

OK - so what does this mean? If it's SharePoint 2013, aim your web service call to one of the REST endpoints within the http://site/_api/ folder.

OK - so now what? There's two paths here. The easy way and the difficult way. Let me show you the easy way first.

Easy Way

Download CAML Designer 2013. Connect to your site. Build your query using CAML Designer's query builder. If this is your first time using CAML Designer, let me give you the 10 cent tour. In the ViewFields tab, drag over the fields you want to retrieve. In the Order By tab, set the sort order for the data. Build your query in the Where tab.

Once you built your query, go to the bottom half of your screen. Click "CSOM Rest." The second line contains the URL needed to make the REST call. If you look at the URL it contains the query.


"/_api/web/lists/getbytitle('Documents')/Items?$select=ID,Author&$orderby=ID&$filter=ID gt '1'"

In this case, I'm querying the Documents library. I want to retrieve the ID and Created By (aka Author) fields, have my results sorted by ID and only retrieve documents with an ID greater than one.

To test what you get outside of CAML Designer, you can copy this string and add it to the end of your site's URL: http://site/_api/web/lists/getbytitle('Documents')/Items?$select=ID,Author&$orderby=ID&$filter=ID gt '1'. Be sure to remove the quotation marks at the beginning and the end. We'll return to the results here in a minute.

At Rightpoint we have a sign that says "Code hard. Don't hard code." Ideally you're not building a hard coded REST call. Imagine in the example above that gt'1' in the workflow is really gt'[WorkflowVariable:ID]'. Indulge yourself and play around with the URL by throwing in some possible workflow variables.

For users of third-party workflow solutions, CAML Designer should feel similar to building a web service call with Nintex or K2. Building a query in CAML Designer also removes the frustration of manually building a query and trying to test it in SharePoint Designer. This is an essential tool and will become your best friend for the rest of your workflow development life.

The only limitation of CAML Designer is if you want to work with objects that are not list items. For example, you cannot build a query to retrieve all subsites with the word "Awesome" in the title. But that should not stop you from using the tool. Perhaps there is a tool out there that does that, and if so, let me know. If you're feeling bold and zesty, take a look at the end points documented here and take what CAML Designer gives you in terms of query syntax to help build your own, non-list item query from scratch.

Hard Way

The hard way requires you to determine your REST service endpoint. This article should help. Following the examples on the site, you can build your query right in the browser. But seriously, why go the hard way when CAML Designer does most of the magic for you?

Back to the results. If you entered your query into a browser you probably noticed that it looks like an RSS feed (aka XML). This isn't going to be much help to you and your workflow development as you want to work with particular fields.

For the next steps, someone else in the blogosphere already beat me to the punch. Follow the steps in this blog post. To summarize that post or if you identify yourself as among the TL;DR crowd, to get back the manna that is a JSON response, the request headers need to declare that you want JSON back. Once you get that JSON manna, you need to parse the JSON to get what particular field or fields you want. Once you have all of that figured out, return to SharePoint Designer and create a workflow that calls a web service; then parse the JSON Result.

The web service action in SharePoint Designer 2013 is powerful and a lot of fun to use, but without context it can be intimidating and frustrating to work with - especially if it's you’re used to the old school /_vti_bin web service calls. For both web service calling rookies and developers pining for a wizard-style builder, the steps outlined in this post should help you achieve great things in your workflow.