Custom Workflow Activity for Granting Permissions on a SharePoint List

In this post I'll show you how to build a custom workflow activity in Visual Studio 2012 that grants permissions on a SharePoint 2013 list or library to a user or group.

Note: this is part of a series of posts on building workflow activities to manage sites, groups, users and permissions. For a complete list of posts, together with a more detailed walkthrough of how to build a custom workflow activity and make it available in SharePoint Designer, start at the beginning.


You can use the REST API to set permissions on any securable object in SharePoint 2013. However, the object on which you're trying to set permissions must not inherit permissions from a parent object. In the case of lists and libraries, this typically means that you must break permission inheritance before you attempt to set permissions. I described how to create a workflow activity that breaks permission inheritance in a previous post.

Once you've broken any permission inheritance, you grant permissions by adding a new role assignment to the securable object. You can use the REST API to do this. In the case of a list or library, you need to send a web request that resembles the following:

{site collection URL}/_api/web/lists/getByTitle('{List title}')/roleassignments/addroleassignment(principalid={principal ID}, roledefid={role definition ID})

HTTP method:

Not required


Note: I described how to retrieve the integer role definition ID for a given role definition name (i.e. permission level) in a previous post, when I looked at granting permissions on SharePoint sites. In this case, I'm going to use the same Get Role Definition ID helper activity that I described in the previous post.

Build the XAML File

This is the latest in a long series of posts on creating workflow activities, so I'll keep this concise - please refer back to earlier posts if you want a bit more detail on the mechanics of building custom workflow activities for SharePoint 2013. As usual, I'll start by defining the arguments for my Grant List Permissions activity:

In this case, I need the consumer of the activity to provide:
  • The URL of the web that contains the list or library.
  • The title of the list or library.
  • The name of the permission level they want to assign.
  • The login name (title or email will also work) of the principal to whom they want to grant permissions.
The workflow activity will return the response status code returned by the REST API call.

Next, we define our activity variables:

Here we've got a variable to store our REST endpoint, variables to store the integer IDs for the principal and the role definition, and variables to store responses from the REST API call.

The complete activity looks like this:

Let's take a brief look at each of these child activities.

Get Principal ID

Our first task is to get the integer ID of the principal to whom we want to grant permissions, using the login name provided by the activity consumer. I've used a LookupSPPrincipalId activity to do this:

Get Role Definition ID

Next, we need to get the integer ID of the role definition we want to assign to the principal, using the permission level name provided by the activity consumer. Here, I've used a custom helper activity named GetRoleDefinitionId:

Essentially, this helper activity uses a REST query to get the integer role definition ID for a specified role definition name. I described how to create this helper activity in a previous post, Custom Workflow Activity for Granting Permissions on a SharePoint Site.

Assign (build restUrl)

We've now got all the information we need to build our REST URL. I've used an Assign activity to do this:

The full value for the restUrl variable is as follows:
String.Format("{0}/_api/web/lists/getByTitle('{1}')/roleassignments/addroleassignment(principalid={2}, roledefid={3})", webUrl, listTitle, principalId, roleDefinitionId)


The next task is to send our REST request to the server, using an HttpSend activity:

Here, we're sending an HTTP POST request with an empty body to the REST URL we defined in the previous step. We're also assigning the headers, content and status code returned by the service to local variables. As I've mentioned in previous posts, I tend to assign responses to local variables through force of habit - you don't need to create and assign these variables unless you're planning to extract information from the responses.

At this stage you'll also need to configure your request headers by clicking the ellipsis button in the RequestHeaders row:

Assign responseStatusCodeOut

In this final activity, we convert the response status code returned by the REST service into a SharePoint Designer-friendly string format. Returning a response status code is optional - it won't affect the functionality of your activity, but it could be useful if the consumer of your activity wants to perform additional actions, such as sending an email, in the event that something goes wrong.

Build the Actions File

To finalize the Grant List Permissions activity and configure it for use in SharePoint Designer, we need to edit the .actions4 file. In this case, the file should resemble the following:

<Action Name="Grant List Permissions" ClassName="SiteManagementActivities.GrantListPermissions" Category="Site Management" AppliesTo="all">
  <RuleDesigner Sentence="Grant the permission level %1 to user or group %2 on the list named %3 on web %4 (Output: %5)">
    <FieldBind  Field="permissionLevel" Text="Permission Level Name" Id="1" />
    <FieldBind  Field="principalLoginName" Text="Principal Login Name" Id="2" />
    <FieldBind  Field="listTitle" Text="List Title" Id="3" />
    <FieldBind  Field="webUrl" Text="SPWeb URL" Id="4" />
    <FieldBind  Field="responseStatusCodeOut" Text="Response Status Code" Id="5" />
    <Parameter Type="System.String, mscorlib" Direction="In" Name="permissionLevel" />
    <Parameter Type="System.String, mscorlib" Direction="In" Name="principalLoginName" />
    <Parameter Type="System.String, mscorlib" Direction="In" Name="listTitle" />
    <Parameter Type="System.String, mscorlib" Direction="In" Name="webUrl" />
    <Parameter Type="System.String, mscorlib" Direction="Out" Name="responseStatusCodeOut" />

Once you've deployed the solution, activated the feature and cleared the SharePoint Designer cache, you should be able to use the Grant List Permissions activity in SharePoint Designer workflows.

Update 17/11/14: a sample Visual Studio solution containing these workflow activities is now available for download.


Popular posts from this blog

The target principal name is incorrect. Cannot generate SSPI context.

Server-side activities have been updated

Versioning SharePoint Framework Packages