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

In this installment, we’ll focus on the Get Authorization info step. We need to do this step first so that we’re set up to write data later in 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’ll need to shut down SharePoint Designer and reopen it so that it will notice that you’ve enabled all of the stuff above.

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. (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.)

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 this prompt 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).

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; give it one that makes sense to you based on what it actually does. Mine is called Get Auth.

As shown on the ribbon above, 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,
            "FormDigestValue": "0x4FCED17AFEC66558CE8F780C0B30C0C289A2D58AF426746750288C3705FDFE822D2E0DA7E386E0E9A6E9F66FFC1DE45A7013EECC946AF56A8F75756EDE319C62,12 Apr 2016 17:19:33 -0000",
            "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"
        }
    }
}

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’m hoping that seeing what the REST call looks like above will help make this part of the setup make a little more sense.

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:

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

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

Set up the Web Service (REST) Call

Next, we use the Call HTTP web service action to set up the actual call to the SharePoint server.

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.

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.

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, you’ll see that this is the path to the value we want.

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 above 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.

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 this:

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

 

 

Series Navigation

<< Looping Through Content in a SharePoint 2013 Site Workflow – Part 3 – High Level View of the Workflow