Site Workflows are great, but if you want them to reach across into other sites, you’ll probably have permission issues. By giving these workflows App Permissions, you’ll be able to let your workflow access content across your Site Collection.
In part one of this series I described the basic task we’re trying to solve. We want to create a SharePoint 2013 site workflow that can iterate through subsites and then take some actions on each item that meets some criteria. At the end of that article, I said that the first step is that we’ll set up the workflow with proper permissions so it can traverse content across the Site Collection. So now you’re thinking, “Great. The problem is defined. Let’s pop over to SharePoint Designer and create a workflow.” Unfortunately, that isn’t the right thing to do. I know because I tried that, and I’m writing this series to pass on the lessons learned.
Before we can even think about writing the workflow, we should set up the authorization side of things. It wasn't enough to get the digest token from the server for the REST calls. (More on this later.) When I tried to make the REST calls I needed from one subsite into the root of the Site Collection or another subsite, I got authorization errors.
Instead, there’s more heavy-duty permissions set up required to make the REST calls into other Webs (sites to normal people). We need to give our workflow App Permission, which isn’t obvious as you’re working on the workflow in SharePoint Designer (SPD), nor is it possible to do so in SPD.
Luckily I have good friends in the community. Matt Bramer (@ionline247) was the first person who replied to one of my tweets, and he gave me some good tips. Through him I found that Fabian Williams (@fabianwilliams) had written several blog posts about the trials and tribulations he went through so that I (and you) wouldn't have to. (I added links to Fabian’s blogs at the end of this article.) But setting up workflow App Permission is still confusing, in my opinion.
You’ll go through two main steps to set these permissions. I found the steps generally documented in the MSDN article, Create a workflow with elevated permissions by using the SharePoint 2013 Workflow platform, but here's my version.
Step 1: Allow the workflow to use app permissions
Go to Site Settings in the site where you want the workflow to run and turn on the Workflows can use app permissions feature. You can do this by going to Site Settings and in the Site Actions section, choose Manage Site Features. Toward the bottom of the list of available features, you’ll see Workflows can use app permissions. To activate it, (figure 1) simply click the Activate button and wait for the activation to complete.
Figure 1: In Site Settings / Site Actions / Manage Site Features you need to Activate the feature to allow workflows to read from and write to all items in the site.
Step 2: Grant full control permission to the workflow
This step gets pretty weird. We have to give this workflow the permissions to run as if it's an a
pp add-in. (Though one might say that it's an a pp add-in already – everything is an a pp add-in, right?)
In the site where you want the workflow to run, navigate to Site Settings and then under Users and Permissions, go to Site app permissions. If things have gone according to plan, you should see Workflow as one of the two or more items listed here.
What you want to grab is the yellow text in figure 2. It follows a bar character - "|" - and precedes an "@" character. I’m not sure exactly where this GUID comes from, but it’s what you need.
Figure 2: Copy part of the workflow app identifier.
Now you have to navigate to a hidden, super-secret page at:
In the example on MSDN, they send you off to the /sites/AppCatalog Site Collection for this. That's only because they are showing an example interacting with a list there. You should go to the secret page in the Site Collection where you want the workflow to run. (Yes, I was down a rat hole on this for a while. Maybe I was just being stupid. It seemed like the good folks who wrote the MSDN article were telling me I needed to give permissions on the App Catalog site for this to work – but that wasn’t the case.)
The secret page you are looking for should look something like figure 3. The page doesn’t have a title like most SharePoint pages (hey, it’s super-secret), but the hover text for the info icon at the top of the page says “Grant permission to an app.”
Figure 3: You’ll paste the Workflow App Identifier into the Add Id field on the secret page.
Now as you can see in figure 4, you paste in the yellow text from above, and click the Lookup button. The next three fields will be filled in. You shouldn't need to change anything in those fields.
Figure 4: Paste in the App Id that you copied from the workflow in Site app permissions (figure 3).
Next, you need to paste some XML into the last field called Permission Request XML. Don't try to get all smart about it like I did. You should paste in EXACTLY this XML – don't make any changes.
You have two options here (the first option adds /web in line three) and I’ll explain the difference below the XML snippet:
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
<AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
In this case, I went with the second option; I want my workflow to have permissions on the entire Site Collection. The first option would give my workflow permissions only in the subsites of the Site Collection; I needed permission on the root of the Site Collection because I wanted to iterate through the subwebs (subsites) from there. So with both the App Id and the XML pasted, the app identity and permission look like figure 5.
Figure 5: We’ve identified the workflow’s app’s identity and indicated where it has permissions to be used.
Next you'll be asked if you trust the workflow. One would think this would be a given, but click Trust It.
Figure 6: Trust your workflow for this Site Collection.
At this point, you have the permissions set up that give you the possibility of looping through the subsites off the root, even though you haven’t created an actual workflow yet. (Or, if you’re like me, you beat your head against the workflow first and then realized you had to figure this part out.)
In the next article, we’ll talk through what the workflow needs to do on a high level to be useful.
References for this article