SharePoint Online: Set List Item Permissions using SharePoint Designer Workflow and REST API

Business Requirement: In “Project Documents” SharePoint Online document library, Project related documents are getting uploaded by the project team. This library has “Permissions” drop-down column (metadata) with values “Restricted” and “Non-Restricted”. If the Permission is restricted, we need to break the permissions of the document, remove all users and groups from it and add “Project Teams” SharePoint group to it. If its “Non-Restricted”, then the document should inherit permissions from its parent library.

Challenge: Unfortunately, we don’t have any permissions related workflow actions available in SharePoint designer workflows! We don’t have any 3rd party workflow products available in the tenant (Nintex is my choice!)

Solution:

Use SharePoint Designer Workflow “Call HTTP Web Service” action and REST APIs to set up permissions on the document. SharePoint Designer 2013 workflows provide a convenient way to automate this process, allowing us to change the permissions for items in a list or library with ease.

Prerequisite: Please note, You must activate “Workflow can use app permissions” site feature and grant full control permission to workflow as per: https://community.nintex.com/t5/Community-Blogs/O365-Call-HTTP-Web-Service-failed-Unauthorized-quot-Access/ba-p/79186, Otherwise, Your REST API Calls would end up  with error: Unauthorized – {“error”:{“code”:”-2147024891, System.UnauthorizedAccessException”,”message”: {“lang”:”en-US”,”value”:”Access denied. You do not have permission to perform this action or access this resource.”}}}

Create Workflow to Set List Item Permissions – Step by Step

Open SharePoint Designer 2013 and add a list workflow of type SharePoint 2013 workflow.

Step 1: Create a dictionary object requestHeader, by adding these two string values in it:

• accept : application/json;odata=verbose
• content-type : application/json;odata=verbose

We need this header to get the response in JSON format as SharePoint REST APIs returns XML.

Step 2: Click on “Condition” >> Select “If any value equals value” from the ribbon. Change the “If” condition to: Current Item: Permissions equals Restricted.

Step 3: Insert a “Step” and “App Step” to it from the ribbon. I’ve used steps to organize the workflow. Also, I used “App Step” to execute workflow actions from the context of workflow author with “Full Control” access rights. Steps inside App Step runs with elevated permissions in the workflow.

Step 4: Select “App Step” and Click on “Action” >> Insert “Call HTTP web Service” from the ribbon.

Step 5: Right Click on the “Call HTTP Web Service” action and select “Properties”.

Set these properties of the action:

• Address: Click on the little ellipses (Three dots) button, which opens a “String Builder” window and frame this string:  [%Workflow Context:Current Site URL%]_api/web/lists/getbyTitle(‘[%Workflow Context:List Name%]’)/items([%Current Item:ID%])/breakroleinheritance(copyRoleAssignments=false, clearSubscopes=true)
• Request Type: HTTP POST
• RequestHeaders: Variable: requestHeader (which we created in step 1)
• ResponseContent: Create New Variable >> Provide a Name and Set the type as “Dictionary”
• ResponseStatusCode: Create New Variable >> Provide a Name and Set the type as “String”

Leave other parameters and click on OK. This step breaks permissions of the list item and removes all existing permissions.
Step 6: Grant Permissions to Required Users/Groups:
The next step is to provide access to a SharePoint group. Here We’ve to use a REST API call addroleassignment with the ID of the Principal and Role definition.  Insert “Call HTTP Web Service” action and here is the text to use in String Builder: [%Workflow Context:Current Site URL%]_api/web/lists/getByTitle(‘[%Workflow Context:List Name%]’)/items([%Current Item:ID%])/roleassignments/addroleassignment(principalid=25,roleDefId=1073741826)

Here I’ve used the ID of a SharePoint Group and Role definition as “Read”.

Step 7: If the Permission Type is “Non-Restricted”, we got to reset inheritance and restore permissions from the parent of the item. Here is the REST API Call to restore inheritance:
[%Workflow Context:Current Site URL%]_api/web/lists/getbyTitle(‘[%Workflow Context:List Name%]’)/items([%Current Item:ID%])/resetroleinheritance

Set the workflow to trigger on item creation and change. Save and Publish the Workflow. Here is how my workflow looks like:

Summary

In Summary, By using a SharePoint Designer 2013 workflow, you can simplify the process of changing item-level permissions in a SharePoint Online list or library. The workflow is designed to run as a “App Step” to execute actions with elevated permissions, making it easy to add or remove users and assign them the appropriate roles. With a SharePoint Designer 2013 workflow in place, you can streamline the process of managing item-level permissions and ensure that users have the right level of access to the information they need.

Tips: You can get the ID of a SharePoint user or Group from the browser URL. E.g. https://Tenant.sharepoint.com/_layouts/15/people.aspx?MembershipGroupId=5 You can also retrieve the Principal ID of a User from: https://Tenant.SharePoint.com/_api/web/siteusers and for SharePoint groups, use: https://tenant.SharePoint.com/_api/web/sitegroups. Similarly, Role definition IDs are at: https://tenant.SharePoint.com/_api/web/roledefinitions