Four steps are involved in updating share permissions on a list:
- Breaking inheritance on the list
- Granting access to the list
- Breaking inheritance on a list item
- Granting access to a list item
This blog will step through all four of these steps to add share access to a particular list item. In the examples that follow, ‘FA Test’/’ListName’ refers to the text name of list you are working with, ‘ListID’ refers to the numeric ID of the list, ‘ItemID’ refers to the numeric ID of the item in the list and ‘UserID’ refers to the numeric ID of the user being granted permission. When working with REST calls, make sure that the Workflow App Permissions are scoped correctly otherwise you could receive an ‘Unauthorized’ response (See Scoping). Also note that you could specify the sharing process in 5 simple steps without having to redefine the Header each time
Many thanks to Jason Lee (Custom Workflow Activity for Granting Permissions on a SharePoint Site) and Bijay Kumar (SharePoint 2013 Add User to SharePoint group using REST API) for sharing their knowledge
Define the header dictionary
This step defines the header format that will be used by all four of the functions mentioned previously.
Create a dictionary variable that will tell the system to return values in JSON format.
Click on ‘this’ and use the ‘Add …’ button to define the dictionary names ‘Accept’ and ‘Content Type’ with both having exactly the same value: ‘application/json;odata=verbose’. I replace the ‘Variable:dictionary’ with my standard ‘Header’ dictionary
Break inheritance on a list (breakroleinheritance)
Since you will be defining custom permissions for the list, you will need to break the role inheritance. This will not change permissions, but will simply change the current users to ‘specified’ rather than ‘inherited’ permissions
Define the REST call in a string variable
[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/breakroleinheritance
Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method
We are still not finished with the web service. Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created
That is all that is needed to break the role inheritance – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly
Grant access to the list (addroleassignement)
Once the role inheritance is broken, we need to add the user to the list permissions. Use these actions to give a user or group access to a list (performed prior to granting unique permissions to a list item)
Define the REST call in a string variable
Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:Created By%] is returning the ‘User Id Number’
[%Workflow Context:Current Site URL%] /_api/web/lists/GetByTitle(‘ListName’)/roleassignments/addroleassignment (principalid=UserGroupID , roleDefId=1073741826)
Set the values in the string builder as follows:
principalid: ID of the user or group receiving permissions on the list
roleDefId: A role definition ID. The standard Microsoft 10 digit out of the box ID’s are as follows:
Full Control: 1073741829
Read: 1073741826
Contribute: 1073741827
See my post on getting the Role ID values – useful for custom permission definitions
Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method
We are still not finished with the web service. Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created
That is all that is needed to allow the user to access the list – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly
Break inheritance on a list item (breakroleinheritance)
You would perform this call prior to granting unique permissions to a list item. This is similar to the call to break inheritance on a list, except that here we specify the list item ID on which to break inheritance
Define the REST call in a string variable
Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:SourceID%] is returning the ID of the list item
[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/getItemById (ItemID)/breakroleinheritance
Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method
We are still not finished with the web service. Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created
That is all that is needed to break the role inheritance – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly
Share an item with a user
You would perform this call after you have broken permissions on the list and list items and granted the user in question access to the list. These processes were covered in the previous three HTTP Calls)
Define the REST call in a string variable
Once you have created the header dictionary, set a workflow variable to the string value of the REST call. In the example shown below, [%Current Item:SourceID%] is returning the ID of the list item while [%FA Test:Created By%] is returning the ‘User Id Number’
[%Workflow Context:Current Site URL%]_api/web/lists/GetByTitle(‘ListName’)/getItemById(ItemID)/roleassignments/addroleassignment (principalid=UserID, roleDefId=1073741829)
Use a ‘Call HTTP Web Service’ action to make the REST call using the string previously defined with an HTTP POST method
We are still not finished with the web service. Click on the right combo-box of the ‘Call’ action and select ‘Properties…’ Set the RequestHeaders to the ‘Header’ dictionary previously created
That is all that is needed to allow the user to access the list item – no results are returned. Simply check the ‘ResponseStatusCode’ variable to make sure the call functioned correctly
Set a string variable to the name of the permission level whose Role ID you require.
