Looping Through Content in a SharePoint 2013 Site Workflow, Part 4: Get Authorization Info

Marc Anderson

by Marc D Anderson on 4/15/2016

Share this:
Print

Article Details

Date Revised:
4/15/2016

Applies to:
authorization, rest, SharePoint workflow, workflow steps


If you’ve missed the earlier articles in this series, look to the navigation on the right and you can read through the previous articles.

In this installment, we’ll focus on the Get Authorization info step (Figure 1). We need to do this step first so that we’re set up to write data later in the workflow.

The authorization stage of the workflow
Figure 1: In this article we’ll work on the authorization stage of the workflow.

Remember that we were actually trying to create a workflow. If you’ve gotten this far, I’ll forgive you if you’ve already forgotten what the point of the exercise is! But planning is important.

If you got ahead of yourself by creating the workflow first (like I did), you may need to shut down SharePoint Designer and reopen it so that it will notice that you’ve enabled app permissions, as I outlined in Part 2.

Now that we have the heavy cabling in place, we need to build the workflow so that it has the permissions it needs. For this, we need to make the REST calls into other sites/subsites in an App Step (Figure 2). (It’s App Step in SharePoint Designer, and since SharePoint Designer is at a dead end, it may always be, never becoming an Add-In Step.)

In SharePoint Designer you insert an App Step
Figure 2: In SharePoint Designer you insert an App Step, not an Add-in Step.

What we will be doing is wrapping any REST calls that reach into other Webs (sites) in an App Step. Once you’ve done this, you’ll get  the prompt shown in Figure 3 when you publish the workflow. I’d call this the “Are you really, really, really sure?” prompt. You’ll see this every time you publish the workflow from now on – pretty much (it seems sort of sporadic).

SharePoint Designer verifies that you really want to publish the workflow
Figure 3: SharePoint Designer verifies that you really want to publish the workflow.

REST Considerations

There’s a real chicken and egg issue with using REST calls in SharePoint Designer workflows. If you haven’t made REST calls before – outside SPD workflows – the REST calls themselves will be like black magic to you. Even if you have done REST calls before, the way it works in SPD workflows is pretty clunky. So what should you learn about?

Well, you can follow a cookbook approach like in this series of posts as well as the references I provide, or you can go whole hog and learn how it really works. It’s really up to you. If you think you’ll want to make REST calls in other contexts, learning how to do it in the context of an SPD workflow is probably a bad way to go about it. If you learn about it in this context, it may make less sense outside SPD workflows. Your call.

Set Up the App Step

When you first create your Site Workflow, you’ll have a Stage named Stage 1. As with most Microsoft tools, SharePoint Designer gives your Stage an arbitrary name; you should rename it to one that makes sense to you based on what it actually does. As you can see in Figure 4, I named mine Get Auth.

Rename the default name for the stage
Figure 4: Rename the default name for the stage to one that makes sense to you.

As shown on the ribbon in Figure 4, add an App Step to your workflow.

Set Up for Authorization in the Workflow

When you make only GET REST calls in a workflow (basically translating to read-only), you won’t need this step, but I set it up because I know I will be doing POSTs (making changes to items) down the road. The only goal of this step is to get the form digest value we’ll need to make those updates later.

The actual REST call looks something like this, which is pretty simple:

$.ajax({
 url: _spPageContextInfo.siteServerRelativeUrl +
      "/_api/contextinfo",
 method: "POST",
 contentType: "application/json;odata=verbose",
 headers: {
    "Accept": "application/json;odata=verbose"
 }
});

It’s a POST because it has to be, even though we’re simply requesting data. It’s a little simpler when we’re issuing the request like we are above. I can paste this code into a browser console (assuming jQuery is already loaded) and I get back a result that looks something like this:

{
    "d": {
        "GetContextWebInformation": {
            "__metadata": { "type": "SP.ContextWebInformation" },
            "FormDigestTimeoutSeconds": 1800,
            "LibraryVersion": "16.0.5131.1207",
            "SiteFullUrl": "https://hostname.sharepoint.com",

            "SupportedSchemaVersions": {
                "__metadata": { "type": "Collection(Edm.String)" },
                "results": ["14.0.0.0", "15.0.0.0"]
            },
            "WebFullUrl": "https://hostname.sharepoint.com"

        }
    }
}

Next, we use the Call HTTP web service action to set up the actual call to the SharePoint server.The only thing we really care about for this workflow is the value for FormDigestValue. That’s sort of like the magic key that we can use when we want to make updates in the workflow later.

To do this in the workflow, it takes a bit more setup. I hope that seeing what the REST call looks like above will help make this part of the setup make a little more sense.

Get Auth stage App Step in the workflow
Figure 5: View of the Get Auth stage App Step in the workflow.

Build the Dictionary

Every REST call you make in your workflow will need a dictionary (think of it as a JSON object), which contains some information about what form the request takes and how you’d like the information back.

To build a dictionary, we use the Build Dictionary action. A dictionary in a SharePoint Designer workflow is just a set of name/value pairs wrapped up in a package, sort of like the headers values in the REST call above.

In this case, you should add three name/value pairs to your dictionary (Figure 6):

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

Add three name/value pairs as strings to the dictionary 

Figure 6: Add three name/value pairs as strings to the dictionary.

Give your dictionary a name; here I’ve named mine requestHeaders.

Set up the Web Service (REST) Call

The web service URL should be the path to the site where you want to make the call, followed by /_api/contextinfo. (We’re asking the server to send us some information about the current context; the form digest is a part of that context.)

The HTTP method has to be HTTP POST, as I mentioned above.

Setting the HTTP web service details parameters
Figure 7: Setting the HTTP web service details parameters.

This action is the one that actually makes the call to the server.

Parse the Results

Next, we need to process the data we get back from the server. We’ve seen above what it looks like, and we have to use the tools available in SharePoint Designer to parse it out.

The data that comes back from the call is also considered a dictionary, so we use the Get an Item from a Dictionary action.

Use the Get an Item from a Dictionary action
Figure 8: Use the Get an Item from a Dictionary action to process the data.

We need to specify three things: the value we’d like to retrieve in XPath notation, the dictionary we’d like to retrieve it from and where we’d like to store the result.

First, set the “item by name or path” to d/GetContextWebInformation/FormDigestValue. If you look at the data above (Figure 9), you’ll see that this is the path to the value we want.

Set the “item by name or path”
Figure 9: Set the “item by name or path”.

Next, set the dictionary name to the name you used in the first step; mine is requestHeaders.

Finally, choose a variable to receive the value. I’m using digestValue. We’ll be able to use this value later in the workflow because we’ve saved it into a variable.

Log the Results

The last action is where I do a little logging to make sure that this step worked. Using the Log to History List action, I emit the responseCode from the request and the value of digestValue variable. The responseCode ought to be “OK” if all went well, and I should see the long string value for the digestValue.

Logging the responseCode and digestValue values in the Workflow History List
Figure 10: We can ensure the step is running correctly by logging the responseCode and digestValue values in the Workflow History List.

Set Up the Transition

At the bottom of the stage we’ve been building, there’s a transition option, which is basically, “What next?” Set it to End of Workflow for now.

Publish and Test

This is a good point to save your workflow and test it. No, it doesn’t do anything of real value yet, but building it up step-by-step is the right way to go. If you see good results in the Workflow History Log, then you can feel comfortable moving on to the next step in the workflow.

You should see something like Figure 11:

The response code we hoped for and the long string value for the digestValue
Figure 11: The response code we hoped for and the long string value for the digestValue.

In the next installment in the series, I’ll show you how to set up the next step: Get Webs.

You can find Marc’s original article and blog here.


Topic: Development

Sign in with

Or register