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.
Endpoint:
HTTP method:
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:
As you can see, in this case we need four pieces of information from the activity consumer:
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:
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:
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.
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.
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>
<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.
I have to apply break inheritance on (Document Library) Item to assign custom permission on item-level.
ReplyDeleteIs it possible with REST API and 2013-Designer workflow ?
If yes then how?
The REST URL is wrong. Instead of "clearSubscope={3}", should be "clearSubscopes={3}", so it's missing and "s" on it.
ReplyDeleteThanks for your articles, they are helping me a lot to understand how to build custom activities.
Thanks Marcus! Now corrected.
Delete