Custom Workflow Activity for Breaking List Role Inheritance

In this post I'll show you how to build a custom workflow activity in Visual Studio 2012 that breaks role inheritance on a SharePoint 2013 list or library.

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.

Fundamentals

This is nice and straightforward. You can use the REST API to break role inheritance on a SharePoint list or library. You need to send a web request that resembles the following:

Endpoint:

{site collection URL}/_api/web/lists/getByTitle('{List title}')/breakroleinheritance(copyRoleAssignments={true/false}, clearSubscopes={true/false})

HTTP method:

POST

You can leave the request body empty, and you don't need to add any request headers if you're doing this from a workflow activity. (If you're doing it from another client platform, you'll need an X-RequestDigest header).

Like it's server-side equivalent, the BreakRoleInheritance method accepts two Boolean arguments:

• CopyRoleAssignments. Set this to true if you want to copy existing role assignments from the parent object before you break inheritance; otherwise false.
• ClearSubscopes. Set this to true if you want to clear existing permissions from children of the current object before you break inheritance; otherwise false.

Build the XAML File

This is post number six of this 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 process. As usual, I'll start by defining the arguments for the Break List Role Inheritance activity:

As you can see, in this case we need four pieces of information from the activity consumer:

• The URL of the web that contains the list or library.
• The title of the list or library.
• A Boolean value for the CopyRoleAssignments argument.
• A Boolean value for the ClearSubscopes argument.

The workflow activity will return the status code returned by the REST service.

Next, I'll define the variables I want to use within my activity:

Here, I've got a variable to store the REST endpoint we want to use together with variables to store the headers, content and status code returned by the service call.

Note: I assign the response headers and response content to workflow variables through force of habit. If you're not planning to use them, you don't need to create or assign them.

The complete activity looks like this:

Assign (build REST URL)

The first task is to build the URL for our REST service call, using the information provided by the activity consumer (i.e. our argument values):

The full value for the restUrl variable is as follows:

String.Format("{0}/_api/web/lists/getByTitle('{1}')/breakroleinheritance(copyRoleAssignments={2}, clearSubscopes={3})", webUrl, listTitle, copyRoleAssignments.ToString().ToLower(), clearSubscopes.ToString().ToLower())

Notice that you need to convert the Boolean argument values to lower-case strings. If the strings are not lower-case, the REST service will throw an invalid argument exception.


HttpSend

Next, we send our REST request to the server:

Here, we're sending an HTTP POST request with an empty body to the REST URL we defined in the previous step. I've also assigned the headers, content and status code returned by the service to local variables - however, as I mentioned earlier, you only need to do this if you plan to make use of these values in some way.


Assign responseStatusCodeOut

In this final activity, we convert the response status code returned by the REST service into a SharePoint Designer-friendly string format:

Build the Actions File

To finish off the Break List Role Inheritance activity, we need to edit the .actions4 file. In this case, the file should resemble the following:

<Action Name="Break Role Inheritance On List" ClassName="SiteManagementActivities.BreakListRoleInheritance" Category="Site Management" AppliesTo="all">
  <RuleDesigner Sentence="Break role inheritance on %1 on the web %2. Copy existing role assignments? %3. Clear subscopes? %4. (Output: %5) ">
    <FieldBind  Field="listTitle" Text="List Title" Id="1" />
    <FieldBind  Field="webUrl" Text="SPWeb URL" Id="2" />
    <FieldBind  Field="copyRoleAssignments" Text="Yes/No" Id="3" />
    <FieldBind  Field="clearSubscopes" Text="Yes/No" Id="4" />
    <FieldBind  Field="responseStatusCodeOut" Text="Response Status Code" Id="5" />
  </RuleDesigner>
  <Parameters>
    <Parameter Type="System.String, mscorlib" Direction="In" Name="listTitle" />
    <Parameter Type="System.String, mscorlib" Direction="In" Name="webUrl" />
    <Parameter Type="System.Boolean, mscorlib" Direction="In" Name="copyRoleAssignments" />
    <Parameter Type="System.Boolean, mscorlib" Direction="In" Name="clearSubscopes" />
    <Parameter Type="System.String, mscorlib" Direction="Out" Name="responseStatusCodeOut" />
  </Parameters>
</Action>

When you've deployed the solution, activated the feature and cleared the SharePoint Designer cache, the Break List Role Inheritance activity should be available for use in SharePoint Designer workflows. In my next post, I'll show you how to assign new permissions to the list or library.

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